ChatGLM3 综合 Web Demo 实战指南：对话、工具调用与代码解释器三合一（composite_demo）

大模型AI Agent模型推理服务微调对话系统【免费下载链接】ChatGLM3ChatGLM3 series: Open Bilingual Chat LLMs | 开源双语对话语言模型项目地址https://gitcode.com/zai-org/ChatGLM3点击查看免费下载ChatGLM3 的 composite_demo 是基于 Streamlit 构建的一体化 Web 交互界面它将对话、工具调用与代码解释三大能力封装在同一个页面中开发者只需一条命令即可启动。本文将基于 composite_demo/README.md 的官方说明并结合 composite_demo 目录下的完整源码系统讲解环境安装、模型加载、三种模式的原理与实操以及如何通过注册新工具为模型扩展能力读完即可在本地跑通一个具备 Agent 雏形的 ChatGLM3 演示应用。一、Demo 概览一个页面三种模式ChatGLM3 Web Demo 提供了三种互不冲突的使用模式用户可在页面顶部的模式选择器中随时切换源码见 main.py 中的Mode枚举Chat对话模式与模型进行常规多轮对话可在侧边栏实时调整采样参数与 System PromptTool工具模式模型除对话外还能按需调用已注册的工具如查天气、跑命令完成操作Code Interpreter代码解释器模式模型在 Jupyter 内核环境中实际执行 Python 代码并获取结果可自动连续执行多个代码块以完成绘图、符号运算等复杂任务。下图是 Demo 的完整主界面可以看到三种模式的切换入口、侧边栏参数区与底部对话输入框二、环境安装2.1 创建 Conda 环境并安装依赖官方文档推荐使用 [Conda] 管理 Python 环境Conda 为外部工具实际使用请以其官方文档为准。依次执行以下命令conda create -n chatglm3-demo python3.10 conda activate chatglm3-demo pip install -r requirements.txt注意本项目要求Python 3.10 或更高版本。composite_demo/requirements.txt 中的完整依赖清单如下huggingface_hub0.19.4 pillow10.1.0 pyyaml6.0.1 requests2.31.0 ipykernel6.26.0 ipython8.18.1 jupyter_client8.6.0各依赖的用途分别是huggingface_hub负责从 Hugging Face Hub 拉取模型与分词器client.py 中导入其流式响应类型pillow用于展示代码解释器输出的图片结果pyyaml用于工具模式的 YAML 解析demo_tool.pyrequests被内置天气工具用于调用天气接口ipykernel、ipython、jupyter_client则是代码解释器模式启动 Jupyter 内核的基础。2.2 安装 Jupyter 内核代码解释器模式依赖 Jupyter 执行环境因此在安装依赖后还需要把当前 conda 环境注册为 Jupyter 内核ipython kernel install --name chatglm3-demo --user这里的chatglm3-demo是内核名称demo_ci.py 中的默认值IPYKERNEL os.environ.get(IPYKERNEL, chatglm3-demo)与之对应也就是说内核名称必须与上述命令注册的名称一致否则代码解释器模式将无法启动内核。三、启动 Demo在项目根目录下运行streamlit run main.py启动成功后命令行会输出 Demo 的访问地址默认为http://localhost:8501点击即可打开页面。首次访问时需要下载并加载模型根据网络状况可能需要较长时间。3.1 关键环境变量如果模型已经下载到本地可通过环境变量指定本地路径避免重复下载。以下是 client.py 中定义的全部可配置项环境变量默认值作用MODEL_PATHTHUDM/chatglm3-6b模型路径Hugging Face 仓库名或本地目录TOKENIZER_PATH同MODEL_PATH分词器路径可与模型路径分离PT_PATH无P-Tuning v2 微调 checkpoint 目录路径PRE_SEQ_LEN128P-Tuning v2 前缀序列长度IPYKERNELchatglm3-demo代码解释器使用的 Jupyter 内核名称官方文档给出的两种典型用法# 从本地加载已下载的模型 export MODEL_PATH/path/to/model # 自定义 Jupyter 内核 export IPYKERNELkernel_name3.2 模型加载的实现细节模型加载逻辑封装在 client.py 的HFClient中并通过st.cache_resourceclient.py做了缓存保证 Streamlit 脚本重跑时不会重复加载模型普通场景下使用AutoModel.from_pretrained(MODEL_PATH, trust_remote_codeTrue, device_mapauto)加载并切换为推理模式.eval()ChatGLM3 依赖远程代码执行因此trust_remote_codeTrue是必选项当设置了PT_PATH且路径存在时会以pre_seq_lenPRE_SEQ_LEN的配置加载模型并把 P-Tuning checkpoint 中的transformer.prefix_encoder.权重恢复到模型前缀编码器中从而支持加载微调后的模型源码注释中还提示若使用 int4 量化模型需在.eval()前追加.quantize(bits4, devicecuda).cuda()并去掉device_mapauto且 int4 模型必须在 CUDA 上加载。四、对话模式Chat侧边栏参数与流式输出对话模式下用户可以直接在侧边栏修改以下参数来调整模型行为对应 main.py 的控件定义参数取值范围默认值说明top_p0.0 ~ 1.0步长 0.010.8核采样概率阈值temperature0.0 ~ 1.5步长 0.010.95采样温度越高越随机repetition_penalty0.0 ~ 2.0步长 0.011.1重复惩罚系数Output lengthmax_new_tokens5 ~ 32000256生成的最大新 token 数System Prompt多行文本ChatGLM3 官方默认提示词仅对对话模式生效其中默认的 System Prompt 定义在 main.pyDEFAULT_SYSTEM_PROMPT You are ChatGLM3, a large language model trained by Zhipu.AI. Follow the users instructions carefully. Respond using markdown. .strip()通过修改 System Prompt 可以显著改变模型的回复风格。例如在侧边栏将 System Prompt 设置为“只用 emoji 回复”模型便会在后续对话中严格遵守4.1 流式生成的底层机制对话模式的主逻辑位于 demo_chat.py其核心调用链为client.generate_stream(system_prompt, toolsNone, history, ...)发起流式请求并设置stop_sequences[str(Role.USER)]即遇到|user|特殊 token 时停止生成client.py 中的generate_stream将历史会话转换为system/user/assistant角色结构再交由stream_chat逐 token 产出stream_chatclient.py内部使用自定义的InvalidScoreLogitsProcessor将 NaN/Inf 分数清零并置为token 5同时把eos_token_id扩展为[eos, |user|, |observation|]保证模型在合适位置自然结束前端用postprocess_textconversation.py清理输出中的特殊 token并通过markdown_placeholder.markdown(output_text ▌)实现打字机式的流式渲染效果。另外conversation.py 中的Role枚举将角色映射为 ChatGLM3 的特殊 token|system|、|user|、|assistant|、|observation|这是三种模式统一处理对话状态的基础。五、工具模式Tool零成本注册新工具工具模式是 ChatGLM3 Demo 最具扩展性的部分。只需在 tool_registry.py 中注册新工具就能增强模型的能力无需修改页面逻辑。5.1 使用 register_tool 注册工具注册一个工具只需两步给函数加上register_tool装饰器按约定写好 docstring 和带Annotated标注的参数。官方文档以get_weather为例给出模板register_tool def get_weather( city_name: Annotated[str, The name of the city to be queried, True], ) - str: Get the weather for city_name in the following week ...声明规则如下函数名 工具名模型调用时使用的标识符函数 docstring 工具说明会被模型读取以决定何时调用该工具参数使用Annotated[类型, 描述, 是否必填]三元组标注其中描述必须是字符串、必填标志必须是布尔值。5.2 注册机制的源码实现tool_registry.py 中的register_tool通过inspect反射机制自动完成工具声明以func.__name__作为工具名inspect.getdoc(func).strip()作为工具描述遍历inspect.signature(func).parameters校验每个参数必须带有typing.Annotated注解否则抛出TypeError从注解中解析出typ类型名、description描述和required是否必填组装成统一的工具定义字典将函数句柄存入_TOOL_HOOKS、将工具定义存入_TOOL_DESCRIPTIONS供后续调用与展示使用。仓库自带了三个可直接运行的示例工具tool_registry.pyrandom_number_generator按种子与范围生成随机数、get_weather通过公开天气接口查询城市天气、get_shell在本地 Linux shell 中执行命令并返回输出是天然的本地 Agent 能力示例。5.3 工具调用的完整闭环工具模式的主逻辑位于 demo_tool.py其执行流程由特殊 token 驱动形成“提问 → 模型声明工具 → 执行工具 → 反馈结果 → 模型总结”的闭环模型生成以|assistant|结束的文本时表示即将发起工具调用模型输出工具名与参数 JSON随后生成|observation|特殊 tokenDemo 通过extract_code从输出中提取参数代码块用eval解析参数并调用dispatch_tool(tool, args)tool_registry.py执行对应函数工具返回值被包装为Role.OBSERVATION对话追加到历史若结果超过truncate_length默认 1024则截断并追加[TRUNCATED]标记整个“生成-调用-反馈”循环最多执行 5 轮for _ in range(5)模型据此继续推理直至完成回答。下图展示了模型在用户询问“巴黎天气”后自主选择get_weather工具、传入城市参数、读取观测数据并组织成自然语言回答的完整过程5.4 Manual mode用 YAML 手动指定工具除了自动读取tool_registry.py中注册的工具页面还提供Manual mode手动模式开关demo_tool.py。开启后可以在一个文本框中直接以 YAML 格式编写工具列表Demo 通过yaml.safe_load解析解析失败会提示YAML format error in tools definition预填的EXAMPLE_TOOL是一个符合 OpenAI 风格函数声明 schema 的天气工具示例demo_tool.py在该模式下工具不会自动执行Demo 会提示Please provide tool call results below:需要用户手动把工具输出粘贴反馈给模型。六、代码解释器模式Code Interpreter让模型真正“动手”代码解释器模式是三种模式中能力上限最高的模型拥有真实的代码执行环境可以完成绘图、符号运算等复杂任务并且会根据对任务完成情况的理解自动连续执行多个代码块直到任务完成。因此这一模式下只需指明希望模型执行的任务即可例如“用 Python 画一个爱心”6.1 专属的 System Prompt代码解释器模式有独立的中文 System Promptdemo_ci.py内容为模型名为 ChatGLM、连接着一台不能联网的电脑、可通过运行 Python 代码完成任务并改进报错代码、可处理用户上传的文件默认存储路径/mnt/data/。6.2 基于 Jupyter 的执行内核该模式的核心是 demo_ci.py 中实现的CodeKernel类它封装了jupyter_client的完整生命周期__init__创建KernelManager以IPYKERNEL环境变量指定的内核启动后端并通过blocking_client()建立阻塞式通信通道execute提交代码执行轮询 iopub 消息直到执行状态回到idle返回 shell 消息与输出内容配套提供execute_interactive、inspect、shutdown、restart、interrupt、is_alive等内核管理方法get_kernel()同样以st.cache_resource缓存保证整个会话复用同一个内核实例。6.3 执行结果与图片回显执行后的结果解析在execute函数demo_ci.py输出含text/plain时按文本返回输出含image/png时通过b64_2_img将 base64 解码为PIL.Image对象在对话中以图片形式展示Conversation数据类中的image字段专门承载该结果见 conversation.py执行超时返回Timed out出错则通过clean_ansi_codes清洗终端转义码后展示 traceback与工具模式一致文本结果超过truncate_length时同样会被截断。生成流程同样由|assistant|、|observation|特殊 token 驱动最多循环 5 轮demo_ci.py因此模型可以“写代码 → 看报错 → 改代码 → 再看结果”地自主迭代直到任务完成。七、使用技巧与注意事项官方文档额外总结了两条高频使用技巧打断生成模型生成文本时可点击页面右上角的Stop按钮随时打断清空对话刷新页面即可清空当前对话记录侧边栏还提供了Clear History按钮与Retry按钮main.py其中Retry会回溯到最近一次用户提问并重新生成回答三种模式均实现了该逻辑。此外从源码可以进一步确认几个易踩坑的点首次运行会从 Hugging Face 下载模型请确保网络可达或提前用MODEL_PATH指向本地模型目录代码解释器模式必须预先执行ipython kernel install --name chatglm3-demo --user且内核名要与IPYKERNEL或默认值chatglm3-demo一致工具的Annotated注解格式必须严格遵循“类型、描述字符串、布尔必填”三要素否则注册时会直接抛出TypeError自定义工具时建议对参数做运行时类型校验参考内置工具的实现异常会以 traceback 形式返回给模型帮助其自我修正。八、总结composite_demo 将 ChatGLM3 的三种核心能力浓缩进一个 Streamlit 页面对话模式提供了灵活的参数调节与流式体验工具模式通过register_tool装饰器实现了声明式工具扩展配合 Manual mode 的 YAML 配置即可快速验证自定义工具代码解释器模式则借助 Jupyter 内核让模型具备了“写代码、跑代码、看结果、再改进”的闭环执行能力。理解 main.py 的模式分发、client.py 的流式客户端、tool_registry.py 的注册机制以及 demo_ci.py 的内核封装是进一步基于这套框架开发 Agent 应用、接入私有工具或微调模型演示的起点。赞分享大模型AI Agent模型推理服务微调对话系统【免费下载链接】ChatGLM3ChatGLM3 series: Open Bilingual Chat LLMs | 开源双语对话语言模型项目地址https://gitcode.com/zai-org/ChatGLM3点击查看免费下载相关推荐ChatGLM3 三合一 Web Demo 实战指南对话、工具调用与代码解释器模式详解ChatGLM3 三合一 Web Demo 实战指南对话、工具调用与代码解释器模式详解 本文以开源仓库 composite_demo 目录下的 README.大模型人工智能微调本地部署AI AgentRAGChatGLM3 Composite Web Demo 实战指南三种交互模式、工具注册与代码解释器的完整解析ChatGLM3 Composite Web Demo 实战指南三种交互模式、工具注册与代码解释器的完整解析 本文以仓库 composite_demo 目录下大模型人工智能微调本地部署AI AgentRAGChatGLM3 Chat Format 对话格式规范多轮对话、工具调用与代码执行全解析ChatGLM3 Chat Format 对话格式规范多轮对话、工具调用与代码执行全解析 导读 本文基于 ChatGLM3 官方 PROMPT_en.md 文大模型人工智能微调本地部署AI AgentRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考