用 Chainlit 给 Python 智能体套一个生产级聊天界面（五分钟起）

新建一个项目目录，装好 chainlit，再写一个能原样回消息的 app.py。这是验证环境的最小闭环。

pip install chainlit openai python-dotenv

# app.py
import chainlit as cl

@cl.on_message
async def main(message: cl.Message):
    # 先把用户说的话原样发回去，确认界面能跑
    await cl.Message(content=message.content).send()

在项目目录里启动（加 -w 会自动打开浏览器）：

chainlit run app.py -w

把 main 里的回显换成一次大模型调用。这里用 OpenAI 兼容接口，换成任意厂商都可以。

import os
from dotenv import load_dotenv
import chainlit as cl
from openai import OpenAI

load_dotenv()
client = OpenAI()

@cl.on_message
async def main(message: cl.Message):
    r = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": message.content}],
    )
    answer = r.choices[0].message.content
    await cl.Message(content=answer).send()

真实 Agent 常要先查资料再回答。用 @cl.step 装饰一个函数，界面就会把它显示成一条独立的步骤，调试和演示都更清楚。

@cl.step(type="tool")
def search_knowledge(q: str) -> str:
    # 这里接你自己的检索 / 工具，返回一段文本
    return "（示例）在资料库中找到：Chainlit 用 @cl.on_message 接收消息。"

@cl.on_message
async def main(message: cl.Message):
    snippet = search_knowledge(message.content)
    r = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user",
                   "content": snippet + "\n\n问题：" + message.content}],
    )
    await cl.Message(content=r.choices[0].message.content).send()

默认每次消息都是独立会话。用 user_session 把历史存起来，下次消息带着上下文一起发，Agent 才像在「连续对话」。

@cl.on_message
async def main(message: cl.Message):
    history = cl.user_session.get("history", [])
    history.append({"role": "user", "content": message.content})

    r = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=history,
    )
    reply = r.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    cl.user_session.set("history", history)

    await cl.Message(content=reply).send()

Chainlit 原生支持文件上传。用户在聊天框传文件后，message.elements 里就能拿到本地路径，读出来再喂给模型。

@cl.on_message
async def main(message: cl.Message):
    text = message.content
    for f in (message.elements or []):
        with open(f.path, "r", encoding="utf-8", errors="ignore") as fh:
            text = text + "\n\n文档内容：\n" + fh.read()[:4000]

    r = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": text}],
    )
    await cl.Message(content=r.choices[0].message.content).send()

演示用本地即可；要给别人用，有两条路：Chainlit 官方云（一键部署，但内容会公开）或自托管（放你自己的服务器，数据不出去）。

# 方式一：本地开发
chainlit run app.py -w

# 方式二：部署到 Chainlit Cloud（需先 chainlit login）
chainlit deploy

# 方式三：自托管（放内网 / 自己的服务器）
#   用 chainlit run app.py 起服务，
#   前面套一层 Nginx 或反向代理并加鉴权