企业官网建设流程全解析

• 大模型
• AI Agent
• 模型推理服务
• 微调
• 对话系统

ChatGLM3 Composite Demo 是 ChatGLM3 系列项目提供的综合 Web 演示模块（位于仓库composite_demo目录），它以 Streamlit 为载体将对话、工具调用与代码解释器三种能力整合在同一页面中。本文将围绕该模块的安装、启动与三种模式展开完整讲解，并结合仓库源码（main.py、demo_chat.py、demo_tool.py、demo_ci.py、client.py、tool_registry.py等）剖析参数含义与底层调用机制，读完后你可以独立部署该演示、自定义注册工具，并理解 ChatGLM3 工具调用与代码执行的完整链路。

一、模块概览：三种模式一个入口

Composite Demo 的核心入口是 main.py，通过streamlit run main.py启动后，页面顶部以单选按钮（radio）形式提供三种模式切换，对应源码中的Mode枚举：

• 💬 Chat（对话模式）：与模型进行纯文本对话，可调整采样参数与系统提示词；
• 🛠️ Tool（工具模式）：模型在对话之外可通过已注册工具执行操作（查天气、生成随机数、执行 Shell 命令等）；
• 🧑💻 Code Interpreter（代码解释器模式）：模型在一个 Jupyter 内核环境中执行代码并获取结果，可完成绘图、符号运算等复杂任务。

页面左侧边栏统一提供top_p、temperature、repetition_penalty、Output length四个滑块参数，以及Clear History（清空历史）与Retry（重试）两个操作按钮。模式选择后，main.py通过match tab语法将对应参数分发给 demo_chat.py、demo_tool.py 或 demo_ci.py 的main()函数执行。

从目录结构看，本模块各文件职责清晰：client.py负责模型加载与流式生成客户端，conversation.py定义角色枚举与对话格式化/后处理逻辑，tool_registry.py提供工具注册与分发机制，三个demo_*.py分别实现三种模式的页面逻辑。

二、环境准备与安装

官方建议使用 Conda 管理环境。按照 README 的安装流程，依次执行：

conda create -n chatglm3-demo python=3.10 conda activate chatglm3-demo pip install -r requirements.txt

注意：本项目要求 Python 3.10 或更高版本，这主要因为源码中大量使用了 Python 3.10 引入的语法特性，例如main.py中的match语句、client.py中的str.removeprefix()/removesuffix()方法，以及X | None类型联合写法。

依赖清单见 requirements.txt，各依赖对应功能如下：

如果希望使用代码解释器模式，还需额外将当前环境注册为 Jupyter 内核（默认内核名为chatglm3-demo）：

ipython kernel install --name chatglm3-demo --user

这一步对应 demo_ci.py 中IPYKERNEL = os.environ.get('IPYKERNEL', 'chatglm3-demo')的默认值：CodeKernel类通过jupyter_client.KernelManager(kernel_name=IPYKERNEL, ...)按该名称启动后端内核。若你注册时使用了其他内核名，可通过环境变量IPYKERNEL指定。

三、启动运行与环境变量

安装完成后，在composite_demo目录下执行：

streamlit run main.py

命令执行后，命令行会打印出 demo 的访问地址，点击即可在浏览器打开。首次访问时，系统需要下载并加载模型，可能耗时较长（默认从 Hugging Face 拉取THUDM/chatglm3-6b）。

如果模型已下载到本地，可通过以下环境变量控制加载行为（定义于 client.py）：

export MODEL_PATH=/path/to/model # 指定本地模型路径（默认 THUDM/chatglm3-6b） export TOKENIZER_PATH=/path/to/tokenizer # 指定分词器路径（默认与 MODEL_PATH 相同） export IPYKERNEL=<kernel_name> # 自定义代码解释器使用的 Jupyter 内核名

client.py中get_client()被@st.cache_resource装饰，模型只会加载一次并在页面重运行时复用。模型加载细节可关注两点：

• 默认通过AutoModel.from_pretrained(MODEL_PATH, trust_remote_code=True, device_map="auto").eval()以自动设备映射方式加载（源码注释提示：如需 int4 量化，可在.eval()前追加.quantize(bits=4, device="cuda").cuda()，且 int4 模型必须用 CUDA 加载）；
• 支持加载 P-Tuning v2 微调 checkpoint：当PT_PATH环境变量指向有效的pytorch_model.bin时，会以pre_seq_len=128（PRE_SEQ_LEN环境变量可调）构建配置，并仅将 checkpoint 中transformer.prefix_encoder.前缀的权重载入 prefix encoder。

四、对话模式：参数调参与流式输出

在对话模式下，用户可直接在侧边栏修改top_p、temperature、repetition_penalty、Output length以及System Prompt来调整模型行为。这些滑块的取值范围与默认值由 main.py 定义：

其中System Prompt文本框默认填充DEFAULT_SYSTEM_PROMPT（提示模型遵循用户指令并以 Markdown 回复），仅对 Chat 模式生效（侧边栏标注为 "Only for chat mode"）。

一个直观的例子是：在系统提示词中要求模型仅用 emoji 回复、不使用普通文字，模型会严格遵守该指令，后续回复全部只输出对应 emoji（见下图），左侧还能看到top_p、temperature滑块与提示词输入框的联动效果。

从源码看，对话模式的生成链路位于 demo_chat.py：main()将历史对话存入st.session_state.chat_history，随后调用client.generate_stream(...)流式生成，关键参数包括：

• tools=None：纯对话模式不启用工具；
• do_sample=True：开启采样；
• stop_sequences=[str(Role.USER)]：以"<|user|>"作为停止序列，防止模型生成越界内容；
• repetition_penalty等采样参数透传给底层。

生成过程中，每个 token 会实时以postprocess_text(output_text + '▌')渲染（▌为光标占位符）；当遇到特殊 token"<|user|>"时结束本轮。postprocess_text（见 conversation.py）会清理 LaTeX 转义（\(→$、\[→$$）以及<|assistant|>、<|observation|>、<|system|>、<|user|>等特殊标记，保证展示层干净。底层HFClient.generate_stream（client.py）则基于transformers的stream_chat实现，并挂载InvalidScoreLogitsProcessor——当采样分数出现 NaN/Inf 时将其清零并压制非法 token，同时把<|user|>、<|observation|>一并加入eos_token_id。

此外，侧边栏的Retry按钮会定位历史中最后一条用户消息并删除其后续记录后重新生成，Clear History则直接清空会话。

五、工具模式：注册、分发与手动模式

5.1 用@register_tool注册新工具

工具模式的核心是 tool_registry.py。要增强模型能力，只需在该文件中用@register_tool装饰一个普通 Python 函数即可完成注册。注册规范如下：

• 工具名称= 函数名；
• 工具描述= 函数 docstring；
• 工具参数= 使用Annotated[typ: type, description: str, required: bool]标注每个参数的类型、描述与是否必填。

例如内置的get_weather工具：

@register_tool def get_weather( city_name: Annotated[str, 'The name of the city to be queried', True], ) -> str: """ Get the current weather for `city_name` """ ...

从register_tool的底层实现看，装饰器会做三件事：

1. inspect.getdoc(func)提取 docstring 作为工具描述；
2. 遍历inspect.signature(func)的每个参数，校验其注解必须为typing.Annotated（否则抛TypeError），并从中解析出类型名、描述字符串与 required 布尔值，组装成{"name", "description", "type", "required"}结构；
3. 将工具存入全局_TOOL_HOOKS（名称→可调用函数）与_TOOL_DESCRIPTIONS（名称→声明字典），启动时打印[registered tool]日志。

随后通过get_tools()导出全部工具声明（返回深拷贝），通过dispatch_tool(tool_name, tool_params)在生成流程中按名称调用具体函数；若工具执行抛出异常，dispatch_tool会返回格式化后的 traceback 文本，而不是中断流程。

仓库自带三个示例工具：

• random_number_generator(seed, range)：按种子在给定区间生成随机整数；
• get_weather(city_name)：调用天气 API 获取指定城市的当前天气（温度、体感、湿度、天气描述、观测时间）；
• get_shell(query)：在 Linux shell 中执行命令并返回 stdout/stderr。

5.2 工具调用的完整链路

工具模式页面逻辑位于 demo_tool.py，其生成循环以特殊 token 作为协议分界：

• 遇到"<|assistant|>"表示模型要发起工具调用，将当前文本作为工具声明追加进历史；
• 遇到"<|observation|>"表示工具调用参数输出完毕：用正则extract_code从 ``` 代码块中取出参数文本，通过eval(code, {'tool_call': tool_call}, {})解析出参数字典，随后调用dispatch_tool(tool, args)执行工具；
• 工具返回结果若超过truncate_length（默认 1024）会被截断并追加[TRUNCATED]标记；
• 观察结果以Role.OBSERVATION追加进历史，模型根据观察结果继续生成，直到遇到"<|user|>"结束本轮。

循环最多迭代 5 轮（for _ in range(5)），避免工具调用死循环。整体上，工具调用被建模为“模型生成工具声明 → 执行工具 → 观察结果 → 继续生成”的对话循环，这一协议与 ChatGLM3 的<|assistant|>/<|observation|>特殊 token 设计一一对应。

下图展示了模型在收到“查查巴黎的天气怎么样？”后自动调用get_weather工具并返回查询结果的实际运行效果：

5.3 Manual mode：YAML 手动指定工具

页面上的Manual mode开关（demo_tool.py 中的st.toggle）允许绕过程序内注册表，直接以 YAML 形式向模型声明工具列表。开启后页面展开一个文本框，默认填入EXAMPLE_TOOL（一个 OpenAI 风格的工具声明，包含name、description、parameters.type、parameters.properties、parameters.required字段），可通过yaml_to_dict()解析为字典列表。

需要注意：手动模式下工具不会自动执行，模型生成工具调用后页面会提示 "Please provide tool call results below"，你需要手动把工具的输出反馈给模型（以观察结果形式继续对话）。该模式适合调试工具声明格式或接入尚未注册的第三方工具协议。

六、代码解释器模式：Jupyter 内核中的自主执行

代码解释器模式让模型获得真实的代码执行能力，可完成绘制图表、符号运算等复杂任务。在此模式下，你只需要描述希望模型完成的任务，模型会根据对任务完成情况的理解自动连续执行多个代码块，直至任务完成。

实现层面，demo_ci.py 定义CodeKernel类封装 Jupyter 内核生命周期：

• 构造时通过jupyter_client.KernelManager(kernel_name=IPYKERNEL)启动后端内核，并初始化blocking_client()与消息通道；
• execute(code)提交代码并轮询 iopub 消息直至execution_state == 'idle'，返回 shell 消息与输出内容；
• 提供restart()、interrupt()、shutdown()等内核管理方法；get_kernel()同样被@st.cache_resource缓存。

execute()函数负责解析执行结果：文本输出以text/plain类型返回；图像输出以image/png（base64）形式返回，通过b64_2_img()转成 PIL Image 后直接渲染在页面中。该模式内置的系统提示词（SYSTEM_PROMPT）明确告知模型：它是名为 ChatGLM 的智能助手、连接着一台不能联网的电脑，可以通过运行 Python 代码并读取结果来解决问题，且用户上传文件默认存放在/mnt/data/。

例如，让 ChatGLM3 "用 Python 画一个爱心"：模型会自动编写绘图代码、在内核中执行，并将生成的 Heart Shape 图形返回给用户，全程无需人工干预：

与工具模式类似，代码解释器也通过特殊 token 协议驱动："<|assistant|>"标记开始输出代码，"<|observation|>"标记代码块结束，随后extract_code抽取代码执行。文本型结果超过truncate_length时同样会被截断。此外demo_ci.py会对代码中的<|observation|>、<|assistant|>interpreter等标记做清洗后再提交内核，避免协议标记混入代码。

七、使用技巧与注意事项

• 中断生成：模型生成文本期间，点击页面右上角的Stop按钮即可打断当前生成。
• 清空历史：刷新页面即可清空对话记录（同时Clear History按钮也提供同样的能力）。
• 模式默认参数差异：三种模式对采样参数的默认值不同——Chat 模式由侧边栏统一控制（top_p=0.8、temperature=0.95、repetition_penalty=1.1），而 Tool 与 Code Interpreter 模式的函数默认值为top_p=0.2、temperature=0.1、repetition_penalty=1.1（见demo_tool.py/demo_ci.py的main()签名），低温度设定更利于模型稳定输出工具声明与代码。
• 工具观察结果截断：工具输出与代码执行结果默认最多保留 1024 字符（truncate_length），超出部分以[TRUNCATED]结尾，可自行调大以支持更长输出。
• 模型序列长度限制：底层stream_chat会校验input_sequence_length + max_new_tokens是否超出模型seq_length，超出时返回提示信息而非崩溃，可通过调小Output length或缩短历史来规避。

至此，你已掌握 Composite Demo 从安装、启动到三种模式全流程的使用方法，也理解了@register_tool注册机制、特殊 token 调用协议、Jupyter 内核执行链路的底层原理。如需进一步扩展，可参考仓库中 langchain_demo、tools_using_demo 等模块，了解工具能力的其他接入形态。

• 大模型
• AI Agent
• 模型推理服务
• 微调
• 对话系统