# 对话历史 Source: https://docs.bigmodel.cn/api-reference/agent-api/对话历史 /openapi/openapi.json post /v1/agents/conversation 查询智能体对话历史，现仅支持 `slides_glm_agent` 智能体。点击 **Try it** 按钮可快速试用。 # 异步结果 Source: https://docs.bigmodel.cn/api-reference/agent-api/异步结果 /openapi/openapi.json post /v1/agents/async-result 查询智能体异步任务的处理结果和状态。点击 **Try it** 按钮可快速试用。 # 智能体对话 Source: https://docs.bigmodel.cn/api-reference/agent-api/智能体对话 /openapi/openapi.json post /v1/agents 与智能体进行对话交互。支持同步和流式调用，提供智能体的专业能力。见 [智能体文档](/cn/guide/agents/translation)。点击 **Try it** 按钮可快速试用。 # 问答 Agent 对话（流式） Source: https://docs.bigmodel.cn/api-reference/agent-api/问答-agent-对话（流式） /openapi/openapi.json post /zrag/agent/chat 基于 ReAct（Reasoning + Acting）推理引擎的流式对话接口。LLM 会根据用户问题自主决定是否调用工具（知识检索、查询重写等），并通过 SSE 实时推送思考过程、工具调用和最终回答。点击 **Try it** 按钮可快速试用。 # 创建 Channel Source: https://docs.bigmodel.cn/api-reference/channel/create /openapi/openapi-channel.json post /agent/forward/v0/channels 创建飞书 Channel，将 Agent 绑定到飞书机器人。连接异步建立，创建后可查询连接状态。 创建飞书 Channel。Caller 必须有目标 Agent 的 owner 权限，所有资源必须属于同一 customer。Agent ID 字符串或省略 version 时在创建时固定最新版本；template 不接受 Tools/MCP/Skills override。 owner 或资源预检调用失败时统一返回固定 500，且不创建 Channel。凭据已识别的鉴权拒绝返回 400；Provider 瞬态故障或并发预检忙返回 503。HTTP 201 只表示预检与保存成功；连接由后台异步建立，请读取 connection_status 与 last_error 判断状态。凭据不会回显。 完整配置 JSON 不得超过 65,535 UTF-8 字节。群聊模板必须包含两个占位符各一次。 # 删除 Channel Source: https://docs.bigmodel.cn/api-reference/channel/delete /openapi/openapi-channel.json delete /agent/forward/v0/channels/{channelId} 删除 Channel 并停止后续连接与回复，保留已有会话和记忆。 删除 Channel，停止渠道连接、会话 worker 和后续回复，并清除 Provider 凭据。已有 Memory Store、Managed Session 和审计记录保留。重复删除返回 404；删除前已发出的远端请求可能完成，但不会继续生成渠道回复。 # 获取 Channel Source: https://docs.bigmodel.cn/api-reference/channel/get /openapi/openapi-channel.json get /agent/forward/v0/channels/{channelId} 获取 Channel 的配置、连接状态与最近错误，不回显凭据。 读取 Channel 的安全结构，包含固定 Agent 版本、共享记忆配置、connection_status、last_error、response_options、private_memory_store_enabled 和 group_prompt_template。凭据不回显；不存在、已删除或属于其他 customer 均返回 404。 # 列出 Channel Source: https://docs.bigmodel.cn/api-reference/channel/list /openapi/openapi-channel.json get /agent/forward/v0/channels 分页列出当前账号的 Channel，返回安全配置，不回显凭据。 按当前 customer 分页列出 Channel。返回安全的 resolved inline template 与 Channel 配置，不返回 credential、计费字段或内部 Identity/Session/binding 标识。 # 更新 Channel 群聊模板 Source: https://docs.bigmodel.cn/api-reference/channel/update /openapi/openapi-channel.json patch /agent/forward/v0/channels/{channelId} 更新 Channel 的群聊提示模板，或恢复默认模板；不支持修改其他配置。 仅更新 channel_config.group_prompt_template；字符串中的 `{{context_note}}` 与 `{{messages}}` 必须各一次，null 恢复默认模板。其他配置字段返回 400。成功后新准备的群聊消息使用新模板；已冻结输入继续使用原模板。 # 列出 Agent Source: https://docs.bigmodel.cn/api-reference/managed-agents--agent/列出-agent /openapi/openapi-managed-agents.json get /agent/managed/v1/agents 分页列出当前账号可访问的 Agent。默认排除已归档资源，可通过 `include_archived` 包含。 新协议默认排除已归档 Agent，include_archived 可显式指定。 # 列出 Agent 版本 Source: https://docs.bigmodel.cn/api-reference/managed-agents--agent/列出-agent-版本 /openapi/openapi-managed-agents.json get /agent/managed/v1/agents/{agentId}/versions 分页列出指定 Agent 的历史版本。每条记录都是该版本的完整 Agent 配置快照，而不是仅包含版本号的摘要。 # 创建 Agent Source: https://docs.bigmodel.cn/api-reference/managed-agents--agent/创建-agent /openapi/openapi-managed-agents.json post /agent/managed/v1/agents 创建 Agent 及其首个不可变版本，配置模型、系统提示词、工具、Skills 与 MCP。 创建 Agent 及其首个不可变版本。可配置模型、系统提示词、内置或自定义工具、Skill 和 MCP Server；配置 MCP Server 时必须同时提供引用同名服务器的 `mcp_toolset`，不使用 MCP 时请省略这两个字段。 # 归档 Agent Source: https://docs.bigmodel.cn/api-reference/managed-agents--agent/归档-agent /openapi/openapi-managed-agents.json post /agent/managed/v1/agents/{agentId}/archive 归档指定 Agent。该操作仅限所有者且幂等，并会同时归档其仍在运行的 Deployment；归档是 Agent 的终止操作。 # 更新 Agent Source: https://docs.bigmodel.cn/api-reference/managed-agents--agent/更新-agent /openapi/openapi-managed-agents.json post /agent/managed/v1/agents/{agentId} 更新 Agent 配置并生成新版本，支持通过 `version` 防止并发覆盖。 更新指定 Agent 并生成新的不可变版本。可带当前 `version`；不一致时返回 409，避免覆盖刚发生的改动。仅所有者可更新，已归档 Agent 不可更新。MCP Server 与 `mcp_toolset` 必须按名称一一对应。 # 获取 Agent Source: https://docs.bigmodel.cn/api-reference/managed-agents--agent/获取-agent /openapi/openapi-managed-agents.json get /agent/managed/v1/agents/{agentId} 获取指定 Agent 的当前版本及完整配置，包括模型、系统提示词、工具、Skill、MCP Server、元数据和归档时间。无读取权限时与资源不存在时均返回 404。 # 列出 Deployment Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/列出-deployment /openapi/openapi-managed-agents.json get /agent/managed/v1/deployments 分页列出可访问的 Deployment，支持按 Agent、状态和创建时间筛选。 分页列出当前身份可读取的 Deployment，支持按 Agent、状态和创建时间过滤。默认不返回已归档记录；传入 `include_archived=true` 可包含已归档 Deployment。归档状态由 `archived_at` 表示，`status` 仍只会是 `active` 或 `paused`。 # 列出 Deployment Run Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/列出-deployment-run /openapi/openapi-managed-agents.json get /agent/managed/v1/deployment_runs 分页查询 Deployment 的运行记录，支持按任务、触发方式、时间和错误筛选。 分页列出当前身份可读取的 Deployment Run，支持按 Deployment、是否有错误、触发方式和创建时间过滤。已归档 Deployment 的历史 Run 仍可查询；Run 是否成功通过 `error` 是否为 `null` 判断，响应中不包含 `status` 字段。 # 创建 Deployment Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/创建-deployment /openapi/openapi-managed-agents.json post /agent/managed/v1/deployments 创建定时或手动触发的 Deployment，固定 Agent 版本、环境与任务输入。 创建一个绑定到指定 Agent 版本和 Environment 的 Deployment。`initial_events` 必须包含 1 至 50 个 `user.message` 事件，且仅支持文本和图片内容块（base64、url 或 file 来源）；图片要求生效模型支持图片输入。省略 `schedule` 或传 `null` 时创建仅支持手动触发的 Deployment；配置 cron 时目前仅支持 `Asia/Shanghai` 时区，并受平台最小触发间隔限制。可同时绑定 Vault、Memory Store 和 File 资源。 # 归档 Deployment Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/归档-deployment /openapi/openapi-managed-agents.json post /agent/managed/v1/deployments/{deploymentId}/archive 归档指定 Deployment 并停止后续定时触发。归档是终态且操作幂等，重复归档不会刷新 `archived_at`；归档后不能更新、暂停、恢复或手动运行。Deployment 没有删除接口。 # 恢复 Deployment Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/恢复-deployment /openapi/openapi-managed-agents.json post /agent/managed/v1/deployments/{deploymentId}/unpause 恢复 Deployment 的后续调度；不会补跑暂停期间错过的任务。 恢复指定 Deployment。该操作幂等；对于 cron Deployment，会从当前时间重新计算下一次未来执行时间，不补跑暂停期间错过的任务；仅手动触发的 Deployment 不会生成下一次执行时间。已归档 Deployment 不可恢复。 # 手动运行 Deployment Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/手动运行-deployment /openapi/openapi-managed-agents.json post /agent/managed/v1/deployments/{deploymentId}/run 立即触发一次 Deployment Run，返回 `202 Accepted`。可查询运行记录和关联会话。 立即为指定 Deployment 创建一次手动触发的 Deployment Run，并返回 `202 Accepted`。手动运行不会推进 cron 的下一次执行时间，可在 Deployment 暂停时执行，但不能对已归档 Deployment 执行。 # 暂停 Deployment Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/暂停-deployment /openapi/openapi-managed-agents.json post /agent/managed/v1/deployments/{deploymentId}/pause 暂停指定 Deployment 的定时触发。该操作幂等：重复暂停不会更新时间；如果 Deployment 已因资源错误自动暂停，则保留原有错误原因。已归档 Deployment 不可暂停。 # 更新 Deployment Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/更新-deployment /openapi/openapi-managed-agents.json post /agent/managed/v1/deployments/{deploymentId} 更新 Deployment 的配置、任务输入与调度，或重新固定同一 Agent 的版本。 更新指定 Deployment 的可变配置。支持 `name`、`description`、`metadata`、`initial_events`、`environment_id`、`vault_ids`、`resources`、`schedule` 和 `agent`；`agent` 只能重新固定同一个 Agent 的版本或覆盖配置，不能切换 Agent ID。`schedule: null` 会改为仅手动触发，`resources: null` 和 `metadata: null` 会清空对应配置，`environment_id: null` 会保留原值。已归档 Deployment 不可更新。 # 获取 Deployment Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/获取-deployment /openapi/openapi-managed-agents.json get /agent/managed/v1/deployments/{deploymentId} 获取指定 Deployment 的当前配置和运行状态，包括固定的 Agent 版本、Environment、资源、Vault、调度计划及初始事件。已归档状态通过 `archived_at` 返回。 # 获取 Deployment Run Source: https://docs.bigmodel.cn/api-reference/managed-agents--deployment/获取-deployment-run /openapi/openapi-managed-agents.json get /agent/managed/v1/deployment_runs/{runId} 获取指定 Deployment Run 的执行记录，包括触发方式、关联 Session、固定的 Agent 版本和错误信息。不存在或当前身份无权读取时均返回 404。 # 列出 Environment Source: https://docs.bigmodel.cn/api-reference/managed-agents--environment/列出-environment /openapi/openapi-managed-agents.json get /agent/managed/v1/environments 分页列出当前身份可访问的 Environment，可使用游标控制顺序和分页大小。 # 创建 Environment Source: https://docs.bigmodel.cn/api-reference/managed-agents--environment/创建-environment /openapi/openapi-managed-agents.json post /agent/managed/v1/environments 创建供 Managed Session 和 Deployment 使用的云端 Environment。可配置预装软件包和网络策略；省略配置时使用平台默认设置。 # 删除 Environment Source: https://docs.bigmodel.cn/api-reference/managed-agents--environment/删除-environment /openapi/openapi-managed-agents.json delete /agent/managed/v1/environments/{environmentId} 永久删除指定 Environment。删除后不能再用于 Session 或 Deployment；不存在或无权限时返回 404。 # 归档 Environment Source: https://docs.bigmodel.cn/api-reference/managed-agents--environment/归档-environment /openapi/openapi-managed-agents.json post /agent/managed/v1/environments/{environmentId}/archive 归档指定 Environment。归档后保留资源记录，但不能再绑定到新的 Session 或 Deployment。 # 更新 Environment Source: https://docs.bigmodel.cn/api-reference/managed-agents--environment/更新-environment /openapi/openapi-managed-agents.json post /agent/managed/v1/environments/{environmentId} 更新指定 Environment 的名称、说明、元数据或云端配置。未提供的字段保持不变；归档后的 Environment 不能再绑定到新的 Session 或 Deployment。 # 获取 Environment Source: https://docs.bigmodel.cn/api-reference/managed-agents--environment/获取-environment /openapi/openapi-managed-agents.json get /agent/managed/v1/environments/{environmentId} 获取指定 Environment 的名称、配置、元数据、状态及归档信息。不可见或不存在时返回 404。 # 上传 File Source: https://docs.bigmodel.cn/api-reference/managed-agents--file/上传-file /openapi/openapi-managed-agents.json post /agent/managed/v1/files 通过 `multipart/form-data` 上传一个 File，供 Session 或 Deployment 作为文件资源挂载。请求必须包含 `file` 字段，并受平台文件大小限制。 # 下载 File 内容 Source: https://docs.bigmodel.cn/api-reference/managed-agents--file/下载-file-内容 /openapi/openapi-managed-agents.json get /agent/managed/v1/files/{fileId}/content 下载指定 File 的原始二进制内容。响应媒体类型和文件名由已保存的文件元数据决定。 # 列出 File Source: https://docs.bigmodel.cn/api-reference/managed-agents--file/列出-file /openapi/openapi-managed-agents.json get /agent/managed/v1/files 新协议返回 data/next_page，旧协议返回 data/has_more/first_id/last_id。ids[] 为不分页批量查 ID 入口，见 Files 指南。 # 删除 File Source: https://docs.bigmodel.cn/api-reference/managed-agents--file/删除-file /openapi/openapi-managed-agents.json delete /agent/managed/v1/files/{fileId} 删除指定 File。已被引用或不满足删除条件时会返回相应错误；不存在或无权限时返回 404。 # 获取 File Source: https://docs.bigmodel.cn/api-reference/managed-agents--file/获取-file /openapi/openapi-managed-agents.json get /agent/managed/v1/files/{fileId} 获取指定 File 的元数据，不返回文件二进制内容。无读取权限时与文件不存在时均返回 404。 # 列出 Memory Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/列出-memory /openapi/openapi-managed-agents.json get /agent/managed/v1/memory_stores/{storeId}/memories 分页列出指定 Memory Store 中的 Memory 条目，可使用游标继续读取。 # 列出 Memory Store Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/列出-memory-store /openapi/openapi-managed-agents.json get /agent/managed/v1/memory_stores 分页列出当前身份可访问的 Memory Store，可使用游标继续读取。 # 列出 Memory Version Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/列出-memory-version /openapi/openapi-managed-agents.json get /agent/managed/v1/memory_stores/{storeId}/memory_versions 分页列出指定 Memory Store 的版本历史，包括创建、更新、删除和脱敏产生的版本。 # 创建 Memory Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/创建-memory /openapi/openapi-managed-agents.json post /agent/managed/v1/memory_stores/{storeId}/memories 在指定 Memory Store 中创建 Memory。`path` 必须以 `/` 开头且不能包含空、`.` 或 `..` 路径段，内容受平台字节数限制。 # 创建 Memory Store Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/创建-memory-store /openapi/openapi-managed-agents.json post /agent/managed/v1/memory_stores 创建一个用于跨 Session 保存长期记忆的 Memory Store。可设置名称、说明和自定义元数据。 # 删除 Memory Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/删除-memory /openapi/openapi-managed-agents.json delete /agent/managed/v1/memory_stores/{storeId}/memories/{memoryId} 删除指定 Memory。删除操作会形成可审计的版本记录，资源不存在或无权限时返回 404。 # 删除 Memory Store Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/删除-memory-store /openapi/openapi-managed-agents.json delete /agent/managed/v1/memory_stores/{storeId} 删除指定 Memory Store，解除活动的 Session 挂载并删除其中的 Memory；版本审计记录会保留但不再可通过已删除的 Store 访问。Store 正在被操作时不能删除。 # 归档 Memory Store Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/归档-memory-store /openapi/openapi-managed-agents.json post /agent/managed/v1/memory_stores/{storeId}/archive 归档指定 Memory Store。归档后保留历史内容，但不能再作为活动资源挂载或写入。 # 更新 Memory Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/更新-memory /openapi/openapi-managed-agents.json post /agent/managed/v1/memory_stores/{storeId}/memories/{memoryId} 更新指定 Memory 的路径或内容。可选 `content_sha256` 前置条件用于避免覆盖并发修改；未提供或为 `null` 的字段保持不变。 # 更新 Memory Store Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/更新-memory-store /openapi/openapi-managed-agents.json post /agent/managed/v1/memory_stores/{storeId} 更新指定 Memory Store 的名称、说明或元数据。元数据使用补丁语义，值为 `null` 时删除对应键。 # 脱敏 Memory Version Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/脱敏-memory-version /openapi/openapi-managed-agents.json post /agent/managed/v1/memory_stores/{storeId}/memory_versions/{versionId}/redact 对指定 Memory Version 执行脱敏，使敏感历史内容不再可读取。该操作针对版本记录，不修改当前 Memory 的业务路径。不能对当前 head 版本脱敏（409）。 # 获取 Memory Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/获取-memory /openapi/openapi-managed-agents.json get /agent/managed/v1/memory_stores/{storeId}/memories/{memoryId} 获取指定 Memory 的当前内容、路径、版本及时间信息。 # 获取 Memory Store Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/获取-memory-store /openapi/openapi-managed-agents.json get /agent/managed/v1/memory_stores/{storeId} 获取指定 Memory Store 的配置、状态、容量和归档信息。不可见或不存在时返回 404。 # 获取 Memory Version Source: https://docs.bigmodel.cn/api-reference/managed-agents--memory/获取-memory-version /openapi/openapi-managed-agents.json get /agent/managed/v1/memory_stores/{storeId}/memory_versions/{versionId} 获取指定 Memory Version 的不可变历史快照。 # 列出 Session Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/列出-session /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions 分页列出当前身份可读取的 Session，并可按 Agent、状态和创建时间等条件筛选。 # 列出 Session Resource Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/列出-session-resource /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId}/resources 分页列出 Session 挂载的 File 与 Memory Store Resource，结果按创建时间稳定排序。 # 列出事件 Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/列出事件 /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId}/events 主线程完整活动及子线程生命周期、消息、阻塞审批摘要；与 Session SSE 同集合。子线程完整活动走 Thread events。支持处理时间过滤与分页。 # 创建 Session Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/创建-session /openapi/openapi-managed-agents.json post /agent/managed/v1/sessions 基于指定 Agent 和 Environment 创建 Session。可选择固定 Agent 版本或提供会话级覆盖，并可附带初始用户消息、File 或 Memory Store 资源及 Vault。 # 删除 Session Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/删除-session /openapi/openapi-managed-agents.json delete /agent/managed/v1/sessions/{sessionId} 删除指定 API Session。运行中的 Session 不能删除；成功后写入删除事件，并尽力清理文件投影和 Checkpoint 等外部运行资源。不存在或无权限时返回 404。 # 删除 Session File Resource Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/删除-session-file-resource /openapi/openapi-managed-agents.json delete /agent/managed/v1/sessions/{sessionId}/resources/{resourceId} 从未归档的 Session 删除指定 File Resource。该操作只解除 Session 挂载，不删除源 File。 # 发送事件 Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/发送事件 /openapi/openapi-managed-agents.json post /agent/managed/v1/sessions/{sessionId}/events 向指定 Session 追加事件并触发后续处理。一次可发送 1 至 10 个受支持事件；已归档 Session 不接受新事件。 # 归档 Session Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/归档-session /openapi/openapi-managed-agents.json post /agent/managed/v1/sessions/{sessionId}/archive 归档指定 API Session，并将其终止后保留历史数据。运行中的 Session 不能归档，已归档 Session 再次归档会返回冲突；归档后不可再追加事件或修改资源。 # 新增 Session File Resource Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/新增-session-file-resource /openapi/openapi-managed-agents.json post /agent/managed/v1/sessions/{sessionId}/resources 向未归档的 Session 新增一个 File Resource。`file_id` 必须属于该 Agent 所有者，`mount_path` 必须有效且不能与现有挂载路径重叠。 # 更新 Session Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/更新-session /openapi/openapi-managed-agents.json post /agent/managed/v1/sessions/{sessionId} 更新 Session 的标题、元数据或 Agent 工具配置。仅允许更新接口声明的字段，已归档 Session 不可修改。 # 获取 Session Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/获取-session /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId} 获取指定 Session 的配置、状态、关联 Agent 与 Environment，以及归档和错误信息。无读取权限时与资源不存在时均返回 404。 # 获取 Session File Resource Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/获取-session-file-resource /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId}/resources/{resourceId} 获取 Session 中指定 File Resource 的挂载信息。Memory Store Resource 通过列表接口返回，不通过该资源详情接口读取。 # 订阅实时事件 Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/订阅实时事件 /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId}/events/stream 通过 Server-Sent Events 订阅指定 Session 的实时事件。该流只推送连接后的新事件；重连时应先调用事件列表接口补齐历史并按事件 ID 去重。 # 轮换仓库凭据 Source: https://docs.bigmodel.cn/api-reference/managed-agents--session/轮换仓库凭据 /openapi/openapi-managed-agents.json post /agent/managed/v1/sessions/{sessionId}/resources/{resourceId} 轮换 Session 中 GitHub 仓库资源使用的凭据。 仅 github_repository 支持，已归档返回 400；File Resource 不支持更新。 # 下载 Skill ZIP Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/下载-skill-zip /openapi/openapi-managed-agents.json get /agent/managed/v1/skills/{id}/versions/{v}/content 下载指定 Skill Version 的 ZIP 内容，用于检查或复用该不可变版本。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 列出 Skill Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/列出-skill /openapi/openapi-managed-agents.json get /agent/managed/v1/skills 分页列出当前身份可访问的 Skill，可使用游标控制排序和分页大小。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 列出 Skill Version Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/列出-skill-version /openapi/openapi-managed-agents.json get /agent/managed/v1/skills/{id}/versions 分页列出指定 Skill 的历史版本，可使用游标继续读取。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 创建 Skill Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/创建-skill /openapi/openapi-managed-agents.json post /agent/managed/v1/skills 上传完整 Skill 目录并创建首个版本。上传包须包含 `SKILL.md`。 通过 `multipart/form-data` 上传一个完整 Skill 目录并创建首个版本。上传内容必须包含顶层目录中的 `SKILL.md`，字段名使用 Skill 内相对路径。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 创建 Skill Version Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/创建-skill-version /openapi/openapi-managed-agents.json post /agent/managed/v1/skills/{id}/versions 为已有 Skill 上传完整目录，创建一个新版本。 重新上传完整 Skill 目录以创建新版本。上传内容必须包含顶层目录中的 `SKILL.md`，字段名使用 Skill 内相对路径。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 删除 Skill Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/删除-skill /openapi/openapi-managed-agents.json delete /agent/managed/v1/skills/{id} 摘牌资源，不检查引用；已固定 Session 保留字节，新引用不可用。最后一个在架版本不能单独删除（400）。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 删除 Skill Version Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/删除-skill-version /openapi/openapi-managed-agents.json delete /agent/managed/v1/skills/{id}/versions/{v} 摘牌资源，不检查引用；已固定 Session 保留字节，新引用不可用。最后一个在架版本不能单独删除（400）。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 获取 Skill Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/获取-skill /openapi/openapi-managed-agents.json get /agent/managed/v1/skills/{id} 获取指定 Skill 的元数据和当前版本信息。不可见或不存在时返回 404。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 获取 Skill Version Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/获取-skill-version /openapi/openapi-managed-agents.json get /agent/managed/v1/skills/{id}/versions/{v} 获取指定 Skill Version 的元数据和不可变版本信息。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 获取最新 Skill 版本 Source: https://docs.bigmodel.cn/api-reference/managed-agents--skill/获取最新-skill-版本 /openapi/openapi-managed-agents.json get /agent/managed/v1/skills/{id}/versions/latest 读取当前 head 版本。删除最后一个在架版本返回 400；已摘牌读取 404。 新旧字段和 latest 固定规则见 [Skill 使用指南](/cn/managed-agents/skills)。 # 列出 Credential Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/列出-credential /openapi/openapi-managed-agents.json get /agent/managed/v1/vaults/{vaultId}/credentials 分页列出指定 Vault 中的 Credential 元数据和认证类型。密钥、Token 等敏感值不会在响应中返回。 # 列出 Vault Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/列出-vault /openapi/openapi-managed-agents.json get /agent/managed/v1/vaults 分页列出当前身份拥有的 Vault。Vault 用于集中管理 Session、Deployment 和 MCP 访问所需的凭据。 # 创建 Credential Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/创建-credential /openapi/openapi-managed-agents.json post /agent/managed/v1/vaults/{vaultId}/credentials 在指定 Vault 中创建 Credential。支持 MCP OAuth、静态 Bearer、通用 OAuth、Bearer 和环境变量凭据；敏感字段只写不回显。 # 创建 Vault Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/创建-vault /openapi/openapi-managed-agents.json post /agent/managed/v1/vaults 创建一个 Vault，用于保存和组织受保护的 Credential。可设置展示名和自定义元数据。 # 删除 Credential Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/删除-credential /openapi/openapi-managed-agents.json delete /agent/managed/v1/vaults/{vaultId}/credentials/{credentialId} 永久删除指定 Credential。删除后相关运行时不能再使用该凭据。 # 删除 Vault Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/删除-vault /openapi/openapi-managed-agents.json delete /agent/managed/v1/vaults/{vaultId} 永久删除指定 Vault，并级联删除其中的 Credential。仅 Vault 所有者可以执行，响应不会返回任何凭据明文。 # 归档 Credential Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/归档-credential /openapi/openapi-managed-agents.json post /agent/managed/v1/vaults/{vaultId}/credentials/{credentialId}/archive 归档指定 Credential。归档后保留记录，但不能再注入到新的 Session 或 Deployment 运行。 # 归档 Vault Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/归档-vault /openapi/openapi-managed-agents.json post /agent/managed/v1/vaults/{vaultId}/archive 归档指定 Vault。归档后保留记录，但其中 Credential 不能再用于新的运行时注入。 # 更新 Credential Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/更新-credential /openapi/openapi-managed-agents.json post /agent/managed/v1/vaults/{vaultId}/credentials/{credentialId} 更新指定 Credential 的展示信息或认证材料，可用于轮换 Token、Secret 和 OAuth 刷新配置；敏感值只写不回显。 # 更新 Vault Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/更新-vault /openapi/openapi-managed-agents.json post /agent/managed/v1/vaults/{vaultId} 更新指定 Vault 的展示名或元数据。元数据使用补丁语义，值为 `null` 时删除对应键。 # 获取 Credential Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/获取-credential /openapi/openapi-managed-agents.json get /agent/managed/v1/vaults/{vaultId}/credentials/{credentialId} 获取指定 Credential 的元数据、认证类型和状态；响应不会返回密钥、Token 或 Secret 明文。 # 获取 Vault Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/获取-vault /openapi/openapi-managed-agents.json get /agent/managed/v1/vaults/{vaultId} 获取指定 Vault 的元数据和状态；响应不返回任何凭据明文。 # 验证 MCP OAuth Source: https://docs.bigmodel.cn/api-reference/managed-agents--vault/验证-mcp-oauth /openapi/openapi-managed-agents.json post /agent/managed/v1/vaults/{vaultId}/credentials/{credentialId}/mcp_oauth_validate 验证指定 MCP OAuth Credential 当前是否能访问其 MCP Server。该操作只执行连通性与认证校验，不返回敏感 Token。 # 创建 Response Source: https://docs.bigmodel.cn/api-reference/response/创建-response /openapi/openapi-responses.json post /v1/responses 创建一次模型响应。`input` 支持文本、图片和文件，可选流式、工具与多轮。详见 [Response API](/cn/guide/develop/responses/introduction)。点击 **Try it** 可试用。 # 删除 Response Source: https://docs.bigmodel.cn/api-reference/response/删除-response /openapi/openapi-responses.json delete /v1/responses/{response_id} 删除已保存的 Response。创建时须 `store=true`。点击 **Try it** 可试用。 # 查询 Response Source: https://docs.bigmodel.cn/api-reference/response/查询-response /openapi/openapi-responses.json get /v1/responses/{response_id} 按 `id` 检索已保存的 Response。创建时须 `store=true`。点击 **Try it** 可试用。 # 查询输入项列表 Source: https://docs.bigmodel.cn/api-reference/response/查询输入项列表 /openapi/openapi-responses.json get /v1/responses/{response_id}/input_items 分页列出某次 Response 的输入项。创建时须 `store=true`。点击 **Try it** 可试用。 # 列出会话线程 Source: https://docs.bigmodel.cn/api-reference/session/threads/列出会话线程 /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId}/threads 列出指定 Session 的线程，包括主线程与成员线程，用于查看状态和继续交互。 # 列出线程事件 Source: https://docs.bigmodel.cn/api-reference/session/threads/列出线程事件 /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId}/threads/{threadId}/events 分页列出指定线程的完整事件历史，按创建时间升序返回。 线程完整历史，data/next_page，按 created_at 升序。 # 归档会话线程 Source: https://docs.bigmodel.cn/api-reference/session/threads/归档会话线程 /openapi/openapi-managed-agents.json post /agent/managed/v1/sessions/{sessionId}/threads/{threadId}/archive 归档处于空闲状态的子线程，保留历史记录。 仅 idle 子线程可归档；running/rescheduling/primary 返回 400，重复归档幂等。 # 获取会话线程 Source: https://docs.bigmodel.cn/api-reference/session/threads/获取会话线程 /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId}/threads/{threadId} 获取指定会话线程的状态、Agent 与用量信息。 # 订阅线程实时事件 Source: https://docs.bigmodel.cn/api-reference/session/threads/订阅线程实时事件 /openapi/openapi-managed-agents.json get /agent/managed/v1/sessions/{sessionId}/threads/{threadId}/stream 实时订阅指定线程的完整事件；仅推送连接建立后的新事件。 live-only；Thread 自己的完整流，primary id 使用 Session 频道。路径不是 /events/stream。 # OCR 服务 Source: https://docs.bigmodel.cn/api-reference/工具-api/ocr-服务 /openapi/openapi.json post /paas/v4/files/ocr 上传图片文件，使用指定工具类型进行 OCR（光学字符识别），支持手写体、文字等识别模式，见 [OCR 服务](/cn/guide/tools/zhipu-ocr)。点击 **Try it** 按钮可快速试用。 # 内容安全 Source: https://docs.bigmodel.cn/api-reference/工具-api/内容安全 /openapi/openapi.json post /paas/v4/moderations 可对文本、图片、音频、视频格式类型的内容进行检测，精准识别涉黄、涉暴、违法违规等风险内容，并输出结构化审核结果（包括内容类型、风险类型及具体风险内容片段），快速定位和处理违规信息。点击 **Try it** 按钮可快速试用。 # 文件解析 Source: https://docs.bigmodel.cn/api-reference/工具-api/文件解析 /openapi/openapi.json post /paas/v4/files/parser/create 创建文件解析任务，支持多种文件格式和解析工具。见 [文件解析服务](/cn/guide/tools/file-parser)。点击 **Try it** 按钮可快速试用。 # 文件解析(同步) Source: https://docs.bigmodel.cn/api-reference/工具-api/文件解析同步 /openapi/openapi.json post /paas/v4/files/parser/sync 创建文件解析任务，支持多种文件格式和解析工具。见 [文件解析服务](/cn/guide/tools/file-parser)。点击 **Try it** 按钮可快速试用。 # 网络搜索 Source: https://docs.bigmodel.cn/api-reference/工具-api/网络搜索 /openapi/openapi.json post /paas/v4/web_search `Web Search API` 是一个专给大模型用的搜索引擎，在传统搜索引擎网页读取、排序的能力基础上，增强了意图识别能力，返回更适合大模型处理的结果（网页标题、`URL`、摘要、名称、图标等）。支持意图增强检索、结构化输出和多引擎支持。见 [网络搜索服务](/cn/guide/tools/web-search)。点击 **Try it** 按钮可快速试用。 # 网页阅读 Source: https://docs.bigmodel.cn/api-reference/工具-api/网页阅读 /openapi/openapi.json post /paas/v4/reader 读取并解析指定 `URL` 的网页内容，可选择返回格式、支持控制缓存、图片保留与摘要选项等。点击 **Try it** 按钮可快速试用。 # 解析结果 Source: https://docs.bigmodel.cn/api-reference/工具-api/解析结果 /openapi/openapi.json get /paas/v4/files/parser/result/{taskId}/{format_type} 异步获取文件解析任务的结果，支持返回纯文本或下载链接格式。见 [文件解析服务](/cn/guide/tools/file-parser)。点击 **Try it** 按钮可快速试用。 # 列出批处理任务 Source: https://docs.bigmodel.cn/api-reference/批处理-api/列出批处理任务 /openapi/openapi.json get /paas/v4/batches 获取批量处理任务列表，支持分页。见 [批量服务](/cn/guide/tools/batch)。点击 **Try it** 按钮可快速试用。 # 创建批处理任务 Source: https://docs.bigmodel.cn/api-reference/批处理-api/创建批处理任务 /openapi/openapi.json post /paas/v4/batches 创建一个新的批量处理任务。见 [批量服务](/cn/guide/tools/batch)。点击 **Try it** 按钮可快速试用。 # 取消批处理任务 Source: https://docs.bigmodel.cn/api-reference/批处理-api/取消批处理任务 /openapi/openapi.json post /paas/v4/batches/{batch_id}/cancel 根据批处理任务`ID`取消正在运行的批量处理任务。见 [批量服务](/cn/guide/tools/batch)。点击 **Try it** 按钮可快速试用。 # 检索批处理任务 Source: https://docs.bigmodel.cn/api-reference/批处理-api/检索批处理任务 /openapi/openapi.json get /paas/v4/batches/{batch_id} 根据批处理任务`ID`获取批量处理任务详情。见 [批量服务](/cn/guide/tools/batch)。点击 **Try it** 按钮可快速试用。 # 上传文件 Source: https://docs.bigmodel.cn/api-reference/文件-api/上传文件 /openapi/openapi.json post /paas/v4/files 上传用于 `Batch 任务`、`智能体` 等功能的文件。注意 `Try it` 功能仅支持小文件上传，实际支持的文件大小请参见下文 `purpose` 相关说明。点击 **Try it** 按钮可快速试用。 # 删除文件 Source: https://docs.bigmodel.cn/api-reference/文件-api/删除文件 /openapi/openapi.json delete /paas/v4/files/{file_id} 永久删除指定文件及其所有关联数据。点击 **Try it** 按钮可快速试用。 # 文件内容 Source: https://docs.bigmodel.cn/api-reference/文件-api/文件内容 /openapi/openapi.json get /paas/v4/files/{file_id}/content 获取文件内容。只支持 `batch` 文件类型。点击 **Try it** 按钮可快速试用。 # 文件列表 Source: https://docs.bigmodel.cn/api-reference/文件-api/文件列表 /openapi/openapi.json get /paas/v4/files 获取已上传文件的分页列表，支持按用途和排序过滤。点击 **Try it** 按钮可快速试用。 # 删除音色 Source: https://docs.bigmodel.cn/api-reference/模型-api/删除音色 /openapi/openapi.json post /paas/v4/voice/delete 删除指定的音色。点击 **Try it** 按钮可快速试用。 # 图像生成 Source: https://docs.bigmodel.cn/api-reference/模型-api/图像生成 /openapi/openapi.json post /paas/v4/images/generations 使用 [GLM-Image](/cn/guide/models/image-generation/glm-image) 等系列模型从文本提示生成高质量图像。通过对用户文字描述快速、精准的理解，让 `AI` 的图像表达更加精确和个性化。点击 **Try it** 按钮可快速试用。 # 图像生成(异步) Source: https://docs.bigmodel.cn/api-reference/模型-api/图像生成异步 /openapi/openapi.json post /paas/v4/async/images/generations 使用 [GLM-Image](/cn/guide/models/image-generation/glm-image) 系列模型从文本提示生成高质量图像。通过对用户文字描述快速、精准的理解，让 `AI` 的图像表达更加精确和个性化。仅支持 `GLM-Image` 模型。点击 **Try it** 按钮可快速试用。 # 对话补全 Source: https://docs.bigmodel.cn/api-reference/模型-api/对话补全 /openapi/openapi.json post /paas/v4/chat/completions 和 [指定模型](/cn/guide/start/model-overview) 对话，模型根据请求给出响应。支持多种模型，支持多模态（文本、图片、音频、视频、文件），流式和非流式输出，可配置采样，温度，最大令牌数，工具调用等。点击 **Try it** 按钮可快速试用。 # 对话补全(异步) Source: https://docs.bigmodel.cn/api-reference/模型-api/对话补全异步 /openapi/openapi.json post /paas/v4/async/chat/completions 和 [指定模型](/cn/guide/start/model-overview) 对话，通过查询异步结果获取模型响应。支持多种模型，支持多模态（文本、图片、音频、视频、文件），可配置采样，温度，最大令牌数，工具调用等。注意此为异步接口，通过 [查询异步结果](/api-reference/%E6%A8%A1%E5%9E%8B-api/%E6%9F%A5%E8%AF%A2%E5%BC%82%E6%AD%A5%E7%BB%93%E6%9E%9C) 获取生成结果。点击 **Try it** 按钮可快速试用。 # 文本分词器 Source: https://docs.bigmodel.cn/api-reference/模型-api/文本分词器 /openapi/openapi.json post /paas/v4/tokenizer `Tokenizer` 用于将文本切分为模型可识别的 `token` 并计算数量。它接收用户输入的文本，通过模型进行分词处理，最终返回对应的 `token` 数量。适用于文本长度评估、模型输入预估、对话上下文截断、费用计算等。点击 **Try it** 按钮可快速试用。 # 文本嵌入 Source: https://docs.bigmodel.cn/api-reference/模型-api/文本嵌入 /openapi/openapi.json post /paas/v4/embeddings 使用 [GLM Embedding](/cn/guide/models/embedding/embedding-3) 系列模型将文本转换为高维向量表示，用于语义相似性和搜索。点击 **Try it** 按钮可快速试用。 # 文本转语音 Source: https://docs.bigmodel.cn/api-reference/模型-api/文本转语音 /openapi/openapi.json post /paas/v4/audio/speech 使用 `GLM-TTS` 将文本转换为自然语音，支持多种声音、情感控制和语调调整。点击 **Try it** 按钮可快速试用。 # 文本重排序 Source: https://docs.bigmodel.cn/api-reference/模型-api/文本重排序 /openapi/openapi.json post /paas/v4/rerank `Rerank` 用于文本重排序，通过接收用户的查询文本及候选文本列表，使用模型计算候选文本与查询文本的相关性得分并返回分数。适用于智能问答、信息检索等场景。点击 **Try it** 按钮可快速试用。 # 文档解析 Source: https://docs.bigmodel.cn/api-reference/模型-api/文档解析 /openapi/openapi.json post /paas/v4/layout_parsing 使用 [GLM-OCR](/cn/guide/models/vlm/glm-ocr) 模型解析文档和图片的布局并提取文本内容。支持图片和`PDF`文档的`OCR`识别，返回详细的布局信息和可视化结果。点击 **Try it** 按钮可快速试用。 # 查询异步结果 Source: https://docs.bigmodel.cn/api-reference/模型-api/查询异步结果 /openapi/openapi.json get /paas/v4/async-result/{id} 查询对话补全和视频生成异步请求的处理结果和状态。点击 **Try it** 按钮可快速试用。 # 视频生成(异步) Source: https://docs.bigmodel.cn/api-reference/模型-api/视频生成异步 /openapi/openapi.json post /paas/v4/videos/generations 通过调用 [视频模型](/cn/guide/models/video-generation/cogvideox-3) 能力生成视频内容。支持多种视频生成方式，包括文本转视频、图像转视频等。注意此为异步接口，通过 [查询异步结果](/api-reference/%E6%A8%A1%E5%9E%8B-api/%E6%9F%A5%E8%AF%A2%E5%BC%82%E6%AD%A5%E7%BB%93%E6%9E%9C) 获取生成视频结果。点击 **Try it** 按钮可快速试用。 # 语音转文本 Source: https://docs.bigmodel.cn/api-reference/模型-api/语音转文本 /openapi/openapi.json post /paas/v4/audio/transcriptions 使用 [GLM-ASR-2512](/cn/guide/models/sound-and-video/glm-asr-2512) 模型将音频文件转录为文本，支持多语言和实时流式转录。点击 **Try it** 按钮可快速试用。 # 音色列表 Source: https://docs.bigmodel.cn/api-reference/模型-api/音色列表 /openapi/openapi.json get /paas/v4/voice/list 获取音色列表，支持按音色名称模糊搜索、按音色类型过滤。点击 **Try it** 按钮可快速试用。 # 音色复刻 Source: https://docs.bigmodel.cn/api-reference/模型-api/音色复刻 /openapi/openapi.json post /paas/v4/voice/clone 使用音色复刻技术，基于示例音频生成指定音色、文本内容的语音合成。点击 **Try it** 按钮可快速试用。 # 上传URL文档 Source: https://docs.bigmodel.cn/api-reference/知识库-api/上传url文档 /openapi/openapi.json post /llm-application/open/document/upload_url 上传`URL`类型的文档或网页作为内容填充知识库。点击 **Try it** 按钮可快速试用。 # 上传文件文档 Source: https://docs.bigmodel.cn/api-reference/知识库-api/上传文件文档 /openapi/openapi.json post /llm-application/open/document/upload_document/{id} 向指定知识库上传文件类型文档，支持多种切片方式和回调。点击 **Try it** 按钮可快速试用。 # 全模态知识库检索 Source: https://docs.bigmodel.cn/api-reference/知识库-api/全模态知识库检索 /openapi/openapi.json post /zrag/retrieval/retrieve 用于检索全模态知识库，支持文本、图片、视频等多模态输入检索，支持向量检索、关键词检索、混合检索，支持查询重写、重排、QA干预等高级功能。点击 **Try it** 按钮可快速试用。 # 创建知识库 Source: https://docs.bigmodel.cn/api-reference/知识库-api/创建知识库 /openapi/openapi.json post /llm-application/open/knowledge 用于创建个人知识库，支持绑定向量化模型、设置名称、描述、背景色和图标。点击 **Try it** 按钮可快速试用。 # 删除文档 Source: https://docs.bigmodel.cn/api-reference/知识库-api/删除文档 /openapi/openapi.json delete /llm-application/open/document/{id} 根据文档`ID`删除文档。点击 **Try it** 按钮可快速试用。 # 删除知识库 Source: https://docs.bigmodel.cn/api-reference/知识库-api/删除知识库 /openapi/openapi.json delete /llm-application/open/knowledge/{id} 根据知识库`ID`删除个人知识库。点击 **Try it** 按钮可快速试用。 # 文档列表 Source: https://docs.bigmodel.cn/api-reference/知识库-api/文档列表 /openapi/openapi.json get /llm-application/open/document 获取指定知识库下的文档列表。点击 **Try it** 按钮可快速试用。 # 文档详情 Source: https://docs.bigmodel.cn/api-reference/知识库-api/文档详情 /openapi/openapi.json get /llm-application/open/document/{id} 根据文档`ID`获取文档详情。点击 **Try it** 按钮可快速试用。 # 知识库使用量 Source: https://docs.bigmodel.cn/api-reference/知识库-api/知识库使用量 /openapi/openapi.json get /llm-application/open/knowledge/capacity 获取个人知识库的使用量详情，包括字数和字节数。点击 **Try it** 按钮可快速试用。 # 知识库列表 Source: https://docs.bigmodel.cn/api-reference/知识库-api/知识库列表 /openapi/openapi.json get /llm-application/open/knowledge 获取个人知识库列表，支持分页。点击 **Try it** 按钮可快速试用。 # 知识库检索 Source: https://docs.bigmodel.cn/api-reference/知识库-api/知识库检索 /openapi/openapi.json post /llm-application/open/knowledge/retrieve 用于检索个人知识库，支持向量检索、关键词检索、混合检索，支持自定义重排模型。点击 **Try it** 按钮可快速试用。 # 知识库详情 Source: https://docs.bigmodel.cn/api-reference/知识库-api/知识库详情 /openapi/openapi.json get /llm-application/open/knowledge/{id} 根据知识库`ID`获取个人知识库详情。点击 **Try it** 按钮可快速试用。 # 编辑知识库 Source: https://docs.bigmodel.cn/api-reference/知识库-api/编辑知识库 /openapi/openapi.json put /llm-application/open/knowledge/{id} 用于编辑已经创建好的个人知识库，仅传入要修改的字段。点击 **Try it** 按钮可快速试用。 # 解析文档图片 Source: https://docs.bigmodel.cn/api-reference/知识库-api/解析文档图片 /openapi/openapi.json post /llm-application/open/document/slice/image_list/{id} 用于获取文件下解析到的图片序号和图片链接映射关系。点击 **Try it** 按钮可快速试用。 # 重新向量化 Source: https://docs.bigmodel.cn/api-reference/知识库-api/重新向量化 /openapi/openapi.json post /llm-application/open/document/embedding/{id} 用于重新向量化文档（重试等操作）。同步返回成功表示调用成功，向量化完成后调用`callback_url`进行通知，也可调用知识详情接口获取结果。多用于`url`知识场景。点击 **Try it** 按钮可快速试用。 # 错误码 Source: https://docs.bigmodel.cn/cn/api/api-code 调用智谱开放平台 API 时，接收到的响应码由两部分组成：外层是 HTTP 状态码，内层是响应体正文中的定义的业务错误码，提供了更具体的错误描述。 | 业务错误码 | HTTP 状态码 | 错误信息 | | :- | :- | :- | | - | 500 | 内部错误 | | 1000 | 401 | 身份验证失败 | | 1001 | 401 | Header 中未收到 Authentication 参数，无法进行身份验证 | | 1003 | 401 | Authentication Token 已过期，请重新生成/获取 | | 1005 | 401 | 已开启二次认证保护，需要二次认证登录。 | | 1113 | 429 | 您的账户已欠费，请充值后重试 | | 1200 | 500 | API 调用失败 | | 1210 | 400 | API 调用参数有误，请检查文档 | | 1211 | 400 | 模型不存在，请检查模型代码 | | 1212 | 400 | 当前模型不支持 `${method}` 调用方式 | | 1213 | 400 | 未正常接收到 `${field}` 参数 | | 1214 | 400 | `${field}` 参数非法。请检查文档 | | 1215 | 400 | `${field1}` 与 `${field2}` 不能同时设置，请检查文档 | | 1220 | 403 | 您无权访问 `${API_name}` | | 1221 | 400 | API `${API_name}` 已下线 | | 1222 | 400 | API `${API_name}` 不存在 | | 1230 | 500 | API 调用流程出错 | | 1234 | 500 | 网络错误，错误id：`${error_id}`，请联系客服 | | 1261 | 400 | Prompt 超长 | | 1301 | 400 | 系统检测到输入或生成内容可能包含不安全或敏感内容，请您避免输入易产生敏感内容的提示语，感谢您的配合 | | 1302 | 429 | 您的账户已达到速率限制，请您控制请求频率 | | 1305 | 429 | 该模型当前访问量过大，请您稍后再试 | | 1308 | 429 | 已达到 `${number} ${unit}` 的使用上限。您的限额将在 `${next_flush_time}` 重置 | | 1309 | 429 | 您的 GLM Coding Plan 套餐已到期，暂无法使用，前往官方续订后即可恢复 [https://bigmodel.cn/claude-code](https://bigmodel.cn/claude-code) | | 1310 | 429 | 您已达到每周/每月使用上限，您的限额将在 `${next_flush_time}` 重置 | | 1311 | 429 | 当前订阅套餐暂未开放`${model_name}`权限 | | 1313 | 429 | 您的账户当前使用模式不符合公平使用策略，请求频率已受到限制。详情请参阅《条款与协议-订阅及自动续费协议》，如需恢复请前往个人中心-编程套餐总览-顶部申请解除限制 | | 1314 | 429 | 您的企业套餐已失效，请联系企业管理员。 | | 1315 | 429 | 该 API Key 仅限企业编程套餐场景使用，请到官网更换对应产品类型的 API Key | | 1316 | 429 | 已达到 5 小时使用上限。主账号余额不足，无法使用超额按量付费。您的限额将在 `{next_flush_time}` 重置。 | | 1317 | 429 | 已达到 7 天使用上限。主账号余额不足，无法使用超额按量付费。您的限额将在 `{next_flush_time}` 重置。 | | 1318 | 429 | 已达到 5 小时使用上限，且已达子账号月消费上限，无法使用超额按量付费，请联系管理员调整。您的限额将在 `{next_flush_time}` 重置。 | | 1319 | 429 | 已达到 7 天使用上限，且已达子账号月消费上限，无法使用超额按量付费，请联系管理员调整。您的限额将在 `{next_flush_time}` 重置。 | | 1320 | 429 | 已达到 5 小时使用上限，且已达企业级月消费上限，无法使用超额按量付费，请联系管理员调整。您的限额将在 `{next_flush_time}` 重置。 | | 1321 | 429 | 已达到 7 天使用上限，且已达企业级月消费上限，无法使用超额按量付费，请联系管理员调整。您的限额将在 `{next_flush_time}` 重置。 | ## 错误响应示例 以下是 curl 请求的响应报文，其中 401 是 HTTP 状态码，1001 是业务错误码。 ``` * We are completely uploaded and fine < HTTP/2 401 < date: Wed, 20 Mar 2024 03:06:05 GMT < content-type: application/json < set-cookie: acw_tc=76b20****a0e42;path=/;HttpOnly;Max-Age=1800 < server: nginx/1.21.6 < vary: Origin < vary: Access-Control-Request-Method < vary: Access-Control-Request-Headers < * Connection #0 to host open.bigmodel.cn left intact {"error":{"code":"1001","message":"Header 中未收到 Authentication 参数，无法进行身份验证"}} ``` > **注：** 使用流式（SSE）调用时，如果 API 在推理过程中异常终止，不会返回上述错误码，而是在响应体的 `finish_reason` 参数中返回异常原因，详情请参考 `finish_reason` 的参数说明。 # 快速开始 Source: https://docs.bigmodel.cn/cn/api/introduction > [!TIP] > > API 文档提供了智谱开放平台 RESTful API 的详细信息，您可以通过点击 Try it 按钮直接调试 API。 智谱开放平台提供标准的 HTTP API 接口，支持多种编程语言和开发环境，同时提供 [SDKs](/cn/guide/develop/python/introduction)。 ## API 端点 智谱开放平台的通用 API 端点： ``` https://open.bigmodel.cn/api/paas/v4 ``` > [!WARNING] > > 使用 [GLM 编码套餐](/cn/coding-plan/overview) 时，需配置专属的 Coding 端点，详情请见[编码套餐快速开始](/cn/coding-plan/quick-start) ## 身份验证 开放平台 API 使用标准的 **HTTP Bearer** 进行身份验证。 您可以在 [API Keys 页面](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 创建或管理密钥。 > [!WARNING] > > 个人套餐、团队套餐、模型标准 API 的 API Key 已分开管理，新建的三种产品类型的 API Key 互不通用，请按需使用。[查看详情](https://docs.bigmodel.cn/cn/coding-plan/notice/api-key-management) API 密钥需通过 HTTP 请求头的 Bearer 认证方式提供。 ``` Authorization: Bearer YOUR_API_KEY ``` > [!TIP] > > 建议将 API Key 设置为环境变量，避免硬编码到代码中，以提高安全性。 ## 调试工具 API 详情页面右上角提供丰富的 **调用示例**，可点击切换查看不同场景的示例。\ 同时提供 API 调试工具，点击 **Try it** 按钮即可快速尝试 API 调用。 * API 详情页面包含多个交互选项，请注意 **切换输入类型下拉框**、**切换标签页** 和 **添加新内容** 等功能。 * 点击 **Add an item** 或 **Add new property** 可添加 API 所需的更多属性。 * **注意**: 切换标签页后需要重新输入或设置之前的属性值。 ## 调用示例 **cURL** ```bash theme={null} curl -X POST "https://open.bigmodel.cn/api/paas/v4/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "glm-5.3", "messages": [ { "role": "system", "content": "你是一个有用的AI助手。" }, { "role": "user", "content": "你好，请介绍一下自己。" } ], "temperature": 1.0, "stream": true }' ``` **Python SDK** **安装 SDK** ```bash theme={null} # 安装最新版本 pip install zai-sdk # 或指定版本 pip install zai-sdk==0.2.3 ``` **验证安装** ```python theme={null} import zai print(zai.__version__) ``` **使用示例** ```python theme={null} from zai import ZhipuAiClient # 初始化客户端 client = ZhipuAiClient(api_key="YOUR_API_KEY") # 创建聊天完成请求 response = client.chat.completions.create( model="glm-5.3", messages=[ { "role": "system", "content": "您是一个有用的AI助手。" }, { "role": "user", "content": "您好，请介绍一下自己。" } ], temperature=0.6 ) # 获取回复 print(response.choices[0].message.content) ``` **Java SDK** **安装 SDK** **Maven** ```xml theme={null} ai.z.openapi zai-sdk 0.3.5 ``` **Gradle (Groovy)** ```groovy theme={null} implementation 'ai.z.openapi:zai-sdk:0.3.5' ``` **使用示例** ```java theme={null} import ai.z.openapi.ZhipuAiClient; import ai.z.openapi.service.model.*; import java.util.Arrays; public class QuickStart { public static void main(String[] args) { // 初始化客户端 ZhipuAiClient client = ZhipuAiClient.builder().ofZHIPU() .apiKey("YOUR_API_KEY") .build(); // 创建聊天完成请求 ChatCompletionCreateParams request = ChatCompletionCreateParams.builder() .model("glm-5.3") .messages(Arrays.asList( ChatMessage.builder() .role(ChatMessageRole.USER.value()) .content("Hello, who are you?") .build() )) .stream(false) .temperature(0.6f) .maxTokens(1024) .build(); // 发送请求 ChatCompletionResponse response = client.chat().createChatCompletion(request); // 获取回复 System.out.println(response.getData().getChoices().get(0).getMessage()); } } ``` **Python SDK(旧)** **安装 SDK** ```bash theme={null} # 安装最新版本 pip install zhipuai # 或指定版本 pip install zhipuai==2.1.5.20250726 ``` **验证安装** ```python theme={null} import zhipuai print(zhipuai.__version__) ``` **使用示例** ```python theme={null} from zhipuai import ZhipuAI client = ZhipuAI(api_key="YOUR_API_KEY") response = client.chat.completions.create( model="glm-5.3", messages=[ { "role": "system", "content": "您是一个有用的AI助手。" }, { "role": "user", "content": "您好，请介绍一下自己。" } ] ) print(response.choices[0].message.content) ``` # 速率限制 Source: https://docs.bigmodel.cn/cn/api/rate-limit 为保障平台服务稳定性、模型资源的公平使用，以及整体服务质量，智谱开放平台对 API 调用实施 **速率限制（Rate Limits）机制**。下面对速率限制的触发场景、常见错误码及应对方式进行详细说明。 > [!TIP] > > **通用 API 用户：** 可通过 [速率限制](https://bigmodel.cn/usercenter/proj-mgmt/rate-limits) 查看您的账户目前各模型可调用的速率； > > **GLM Coding Plan 用户：** 速率（并发数）限制与您的套餐等级相关，平台会根据资源进行动态调整，低峰期享有更高速率，基本原则 Max > Pro > Lite。 ## 一、什么是速率限制？ **速率限制** 是指平台在一定时间窗口内，对单个账户或调用方的 API 并发请求数等进行限制。 在智谱开放平台中，速率限制主要体现在： * **并发请求数限制** * **不同模型设有独立的并发限制** * **不同用户权益等级、不同套餐对应不同的** **并发限制** * **高峰期的动态限流与平台级保护策略** *** ## 二、为什么需要速率限制？ 速率限制是业界大模型 API 的通用做法，其核心目的包括： **1. 保障平台整体稳定性** **：** 防止瞬时高并发请求对模型服务造成冲击；通过设置速率限制，可以最大程度帮助用户保持稳定的体验。 **2. 确保用户间的公平使用** **：** 避免个别账户在高并发场景下占用过多资源，影响其他用户的正常调用。 **3. 防范异常流量或误用行为** **：** 包括程序异常、无限重试、非预期高频调用等情况。 *** ## 三、智谱开放平台速率限制机制说明 ### 1. 按用户权益等级 & 模型维度划分的并发限制 如果您是 API 用户，智谱开放平台对**不同模型设置了不同的并发数上限**。 （可通过 [速率限制](https://bigmodel.cn/usercenter/proj-mgmt/rate-limits) 查看您的账户目前各模型可调用的速率）： * 通用模型 * 图像 / 视频生成模型 * 向量模型 * 实时音视频模型 * …… 同时，速率限制量级和您的用户权益等级相关，（可通过 [用户权益](https://bigmodel.cn/usercenter/equity-mgmt/user-rights) 查看自己的积分与用户权益等级。） > ⚠️ 并发数指的是：**同一时刻正在处理中的请求数量**。 *** ### 2. 按 GLM Coding Plan 套餐等级划分的并发限制 如果您是 **GLM Coding Plan** **套餐用户，速率限制**与**您订阅的** **套餐** **等级**相关。不同套餐用户，默认可用的模型并发上限不同，每个项目开发可使用 Subagent 等方式并发模型调用，我们的推荐使用项目数量如下（[查看我的套餐等级](https://bigmodel.cn/coding-plan/personal/overview)）： * **Lite ：** **建议同时进行单个项目的开发** * **Pro ：** **建议同时进行 1-2 个项目的开发** * **Max** **：建议同时进行 2+ 个项目的开发** > [!NOTE] > > 套餐用户在低峰期将享有更高的并发权益（动态提升），能够支撑更高数量的项目开发。 *** ### 3. 高峰期的限流策略 在业务高峰期： * 若某一账户在短时间内发起**大量并发请求** * 超出该账户在对应模型上的并发上限 平台将基于 **账户维度** 对请求进行限流处理，而非模型永久不可用。 *** ### 4. 平台级服务过载说明 除账户自身速率限制外，平台在以下情况下可能触发 **平台级保护机制**： * 某一模型在短时间内整体访问量激增 * 底层算力资源处于高负载状态 * 平台进行系统维护、扩容或异常恢复 此类情况属于 **平台服务过载**，与单一账户的调用行为无直接关系。 *** ## 四、相关错误码 ### 1. 错误码 1302：触发用户速率限制 **错误含义** > [!CAUTION] > > 您的账户已达到速率限制，请您控制请求频率 **典型原因** * 当前模型的并发请求数已达到账户上限 * 短时间内请求过于密集 **建议处理方式** * 降低并发请求数量 * 增加请求队列或排队机制 * 在必要时提升账户权益等级，提升并发额度（[如何提升用户权益等级](https://docs.bigmodel.cn/cn/guide/platform/equity-explain)）（此条不适用 GLM Coding Plan） ### 2. 错误码 1305：平台服务过载 **错误含义** > [!CAUTION] > > 该模型当前访问量过大，请您稍后再试 **典型原因** * 模型在当前时段整体访问压力较高 * 平台触发了全局保护或临时限流 **建议处理方式** * 稍后重试请求 * 增加重试间隔，避免立即高频重试 * 在业务允许的情况下进行降级或延迟处理 *** ## 五、如何合理应对速率限制？ 我们建议开发者在系统设计中提前考虑以下策略： ### 1. 控制并发与请求频率 * 使用请求队列或并发池 * 避免瞬时“洪峰式”请求 * 避免固定间隔的高频重试 ### 2. 异步请求或批处理 API * 非实时场景可通过批处理方式或异步请求降低并发压力（[Batch API](https://docs.bigmodel.cn/api-reference/批处理-api/列出批处理任务)、[异步请求](https://docs.bigmodel.cn/api-reference/模型-api/对话补全异步)） *** ## 六、如何申请提升速率限制？ > [!TIP] > > **GLM Coding Plan 用户按订阅套餐等级统一并发，暂不支持申请调整。** 若您使用的是**通用 API**，且业务确实需要更高并发能力，可通过控制台提交申请： 1. 进入【[速率限制调整申请](https://bigmodel.cn/rate-limits/form)】 2. 填写以下信息： * 需要调整的模型 * 期望增加的并发数量 * 实际使用场景与业务说明 平台将在 **10 个工作日内完成审核**，审核结果将通过注册手机号或站内通知告知。 # 音视频通话 Source: https://docs.bigmodel.cn/cn/asyncapi/realtime [GLM-Realtime](/cn/guide/models/sound-and-video/glm-realtime) 提供实时音视频通话和多模态交互能力，支持实时语音对话、视频理解、函数调用等功能。
由于浏览器安全考虑禁止 `WebSocket` 添加鉴权认证请求头，无法在此直接体验，使用详情请参考 [Realtime 指南使用](/cn/guide/models/sound-and-video/glm-realtime)。 # 优化模型返回速度 Source: https://docs.bigmodel.cn/cn/best-practice/latency-optimization 大模型应用的整体延迟通常由多种原因造成： ![Description](https://cdn.bigmodel.cn/markdown/1781074898581whiteboard_exported_image%20%285%29.png?attname=whiteboard_exported_image+%285%29.png) 不同业务场景的瓶颈并不完全相同，因此优化延迟时，不建议只关注单次模型调用速度，而应从**模型选择、Prompt 设计、上下文管理、调用链路和交互体验**等多个方面共同优化。 本文整理了几类常见的延迟优化方法，帮助开发者在保证回答质量的前提下，构建响应更快、体验更稳定的大模型应用。 ## 一、选择适合任务的模型和调用方式 不是所有任务都需要使用能力最强的模型。实际业务中，一次用户请求往往会拆分成多个子任务，例如意图识别、问题改写、知识库检索、结果判断、最终回答生成等。不同子任务对模型能力的要求不同，如果全部使用同一个高能力模型，可能会带来不必要的响应时间和成本开销。 ### 1. 选择适合的模型 对于边界清晰、输出简单的任务，可以优先选择轻量模型、高速模型或高性价比模型，例如： * 意图识别 * 文本分类 * 关键词抽取 * 格式转换 * 简单摘要 * 检索 Query 改写 * 规则明确的结构化信息提取 对于复杂推理、长文本生成、代码生成、多轮规划、复杂 Agent 执行等任务，则可以选择能力更强的模型，以保证任务完成质量。 ### 2. 设置模型思考参数 如果使用的模型支持思考模式相关参数，也可以根据任务复杂度进行控制。对于数学推理、复杂规划、多步骤分析等任务，可以开启更充分的思考；对于简单分类、固定格式抽取、短文本改写等任务，则可以关闭或减少不必要的深度思考，从而获得更快的响应。 建议开发者在设计链路时，先拆分任务类型，再为不同环节选择合适的模型，而不是默认将所有步骤都交给同一个模型完成。 ## 二、减少不必要的输出内容 在多数文本生成场景中，模型输出长度会显著影响整体响应时间。输出越长，模型需要生成的 Token 越多，用户等待完整结果的时间也越长。因此，减少不必要的输出，是最直接、最稳定的延迟优化方式之一。 可以从以下几个方面优化： ### 1. 控制输出长度 在多数生成场景中，输出内容越长，模型需要生成的 Token 越多，整体响应时间也会随之增加。因此，控制输出长度是降低延迟最直接的方法之一。 开发者可以从两个层面进行控制：一是在 **Prompt 中明确回答长度和结构**，二是在**接口参数中设置合理的最大输出长度**。前者用于引导模型生成更短、更聚焦的内容，后者用于避免模型输出超出业务预期。 例如，在智能客服、知识库问答、摘要生成等场景中，可以在 Prompt 中加入明确约束： ``` - 请用 3 条要点回答，每条不超过 30 字。 - 请直接给出结论，不需要解释推理过程。 - 请输出简洁版本，控制在 200 字以内。 ``` 相比“请详细回答”、“请完整说明”这类开放式指令，明确长度和结构的 Prompt 更容易让模型生成短而聚焦的结果。 对于输出形式比较固定的任务，还可以进一步限制模型只返回必要内容。例如： ``` 请只输出 true 或 false。 ``` 同时，在确定业务场景不需要长文本时，可以设置合理的最大输出 Token 数，避免模型继续生成不必要的内容。例如，分类、判断、标签抽取等任务通常只需要很短的输出；长文本摘要、报告生成等任务则可以根据实际展示空间和业务需要设置更高的上限。 > [!TIP] > > 需要注意的是，最大输出长度并不是越大越好。如果设置过大，模型可能生成超出预期的内容；如果设置过小，则可能导致回答被截断。实际使用中，建议根据任务类型、前端展示位置和用户需求设置合适范围。 ### 2. 避免重复生成固定模板 对于固定开头、固定结尾、标准说明、免责声明等内容，建议由业务系统拼接，而不是每次都让模型重新生成。 例如，客服场景中可以将固定话术放在前端或后端模板中，只让模型生成真正需要动态回答的部分。这样既能减少输出 Token，也能让内容风格更加稳定。 ### 3. 精简结构化输出字段 在一些业务场景中，模型的输出并不是直接展示给用户，而是供后端程序继续处理。 以智能客服场景为例。智能客服需要先判断用户意图，再决定是否进入退款流程、是否检索知识库、是否转人工。这类场景通常会要求模型输出 JSON，方便系统解析和执行后续动作。 此时，JSON 字段应尽量保持**简洁、稳定和必要**。字段过多、字段名过长，都会增加模型生成内容，也会提高后续解析和维护成本。 例如，用户输入： ``` 我想查一下退款什么时候到账。 ``` 模型可以只输出业务系统真正需要的字段： ``` { "intent": "refund_status", "need_search": true, "query": "退款到账时间查询" } ``` 其中，`intent` 用于识别用户意图，`need_search` 用于判断是否需要检索知识库或订单信息，`query` 用于生成后续检索关键词。相比让模型输出一大段解释，这种结构化结果更短、更稳定，也更适合程序直接读取。 如果字段只供系统内部使用，应避免加入不必要的说明性内容。例如，不建议让模型输出： ``` { "user_intent_description": "用户想要查询退款什么时候可以到账", "whether_knowledge_base_search_is_required": true, "rewritten_search_query_for_retrieval": "退款到账时间查询" } ``` 这类字段虽然更容易被人理解，但对程序解析并没有额外帮助，反而会增加输出长度。实际使用中，应根据业务需要保留必要字段即可。 ## 三、控制输入内容，减少无效上下文 输入内容越长，模型需要处理的信息越多。在长对话、知识库问答、文档分析和 Agent 场景中，如果每次请求都携带大量历史内容、无关材料或重复提示词，就会增加处理成本和响应延迟。 可以从以下几个方面优化输入内容。 ### 1. 清理无关历史对话 多轮对话中，不一定需要把全部历史消息都传给模型。可以根据当前问题，只保留与本轮任务相关的关键信息。 例如，用户连续咨询订单问题时，可以保留订单号、问题类型、已确认状态等信息，而不必完整保留所有寒暄、重复确认和无关上下文。 ### 2. 对长上下文进行摘要 对于较长的历史对话或文档内容，可以先沉淀为结构化摘要，再作为后续输入。 例如： ``` 用户背景： - 用户已购买企业版套餐 - 当前问题是无法查看用量明细 - 已确认账号权限正常 - 需要继续排查组织空间配置 ``` 这种方式比直接传入完整对话更短，也更方便模型抓住重点。 ### 3. 优化 RAG 检索结果 知识库问答场景中，常见问题不是模型能力不足，而是检索结果过多、过长或相关性不足。建议在进入模型前，对检索结果进行筛选和压缩。 可以考虑： * 控制 Top-K 数量 * 去除重复片段 * 优先保留与问题最相关的段落 * 删除网页导航、页脚、版权说明等无关内容 * 对长文档片段做摘要后再输入模型 RAG 场景中，输入内容的质量往往比长度更重要。少量高相关内容，通常优于大量低相关内容。 ### 4. 使用上下文缓存复用重复内容 如果业务中存在大量重复上下文，例如固定系统提示词、长期不变的工具说明、知识库说明、角色设定或历史对话片段，可以结合上下文缓存能力，减少重复内容带来的处理成本。 适合使用上下文缓存的场景包括： * 多轮对话中反复使用相同系统提示词 * 知识库问答中反复使用相同背景材料 * 批量处理任务中反复使用同一套分析规则 * 长文档问答中围绕同一份文档连续提问 为了提高缓存命中效果，开发者可以从以下几个方面优化： #### 4.1 将稳定内容放在 Prompt 前部 在组织 Prompt 时，建议将**长期不变、可复用的内容放在前部**，例如系统角色、回答规范、工具说明、业务规则等；将**每次请求都会变化的内容放在后部**，例如用户本轮问题、检索结果、时间、订单状态等。 例如，知识库问答场景可以按以下顺序组织： ``` 固定部分： - 你是一个企业知识库问答助手 - 回答要求：准确、简洁，不编造 - 如果资料不足，请说明无法确认 - 输出格式：先给结论，再补充依据 动态部分： - 用户本轮问题 - 本次检索到的知识库片段 ``` 这样做的好处是，前半部分在多次请求中保持稳定，更容易被缓存复用；后半部分虽然每次变化，但不会影响前面固定内容的复用效果。 #### 4.2 保持系统提示词稳定 如果希望系统提示词被反复缓存，就不要在每次请求中频繁改写它。即使只是增加时间戳、随机编号、临时说明，或者调整段落顺序，也可能降低缓存命中效果。 不建议这样写： ``` 你是一个客服助手。当前时间是 2026-06-08 14:32:10。 请根据用户问题回答。 ``` 如果时间不是模型判断所必需的信息，可以不要放入系统提示词；如果确实需要时间信息，可以放到用户问题或动态上下文中： ``` 系统提示词： 你是一个客服助手。请根据业务规则准确回答用户问题。 动态上下文： 当前日期：2026-06-08 用户问题：我的套餐什么时候到期？ ``` 这样可以让系统提示词保持稳定，同时保留必要的动态信息。 #### 4.3 把长文档、工具说明和业务规则做成固定模板 在 Agent、文档问答、代码审查等场景中，工具说明、任务规则、评分标准、输出格式往往很长。如果这些内容每次都需要传入，建议整理成稳定模板，避免每次请求临时拼接不同版本。 例如，代码审查场景中，不要每次都让系统随机生成审查标准，而是固定为一套稳定规则： ``` 你是一个代码审查助手，请从以下方面进行检查： 1. 代码可读性 2. 潜在 Bug 3. 性能问题 4. 安全风险 5. 可维护性建议 请按“问题 - 原因 - 修改建议”的格式输出。 ``` 后续每次只替换待审查代码即可 ``` 请审查以下代码： {{code_snippet}} ``` 这样可以让审查规则被反复复用，而真正变化的部分只保留在后面。 #### 4.4 对高频任务使用统一 Prompt 模板 如果同一个业务场景下有多个入口，例如 Web 端、控制台、客服后台都在调用同一个模型能力，建议共用同一套 Prompt 模板，而不是每个入口各写一份类似但不完全相同的提示词。 例如，企业知识库问答可以统一成： ``` 系统提示词： 你是一个企业知识库助手。请严格依据提供的资料回答问题。 如果资料中没有相关信息，请回答“当前资料中未找到明确说明”。 动态输入： 用户问题：{{user_question}} 检索资料：{{retrieved_context}} ``` 这样不仅有利于缓存复用，也方便后续统一维护和评估效果。 #### 4.5 将固定回复交给程序处理 上下文缓存可以减少重复上下文的处理成本，但并不意味着所有固定内容都要交给模型生成。对于高度固定的回复，建议直接由业务系统返回。 例如： ``` - “已收到您的反馈” - “请先登录后再操作” - “当前账号暂无权限” - “请补充订单号” - “系统繁忙，请稍后重试” ``` 这些内容可以在程序中硬编码，或提前配置为模板。只有当用户问题需要自然语言理解、上下文判断或个性化生成时，再调用模型。这样可以直接减少模型请求次数，比单纯依赖缓存更有效。 #### 4.6 观察缓存命中情况 接入上下文缓存后，建议不要只凭感觉判断效果，而是观察接口返回中的缓存命中信息，例如缓存命中的 Token 数、总输入 Token 数、响应时间变化等。 ## 四、减少串行模型调用 很多大模型应用的延迟并不来自单次模型调用，而是来自多个模型调用串行执行。比如一个请求需要先调用模型判断意图，再调用模型改写 Query，再调用模型判断是否检索，最后再调用模型生成回答。如果这些步骤全部串行执行，整体等待时间会被不断放大。 优化思路是：能合并的步骤尽量合并，能并行的步骤尽量并行，能用程序逻辑完成的步骤不要交给模型。 ### 1. 合并相近任务 在知识库问答、智能客服等场景中，用户的表达方式往往是不固定的。例如，下面几种问法本质上可能都在询问同一个问题： ``` - 企业版在哪里看每个人的用量明细？ - 团队成员各自用了多少 token，在哪里查？ - 管理员能不能看到每个成员的调用量？ ``` 如果系统要处理这类问题，通常需要先完成几件事：判断用户意图、判断是否需要检索知识库、把用户问题改写成更适合检索的关键词。 一种比较低效的方式是把这几个步骤拆成多次模型调用： * 第一次模型调用：判断用户意图 * 第二次模型调用：判断是否需要检索知识库 * 第三次模型调用：改写检索 Query 但这三个任务都依赖同一句用户输入，而且输出结果都比较简单，因此可以合并到一次模型调用中完成。 开发者可以提前定义好输出字段和可选意图类型，例如： ``` 请根据用户问题输出 JSON： - intent：用户意图，只能从 usage_detail_query、billing_query、technical_issue、other 中选择 - need_search：是否需要检索知识库 - search_query：如果需要检索，请生成适合知识库检索的关键词；如果不需要，则为空字符串 ``` 当用户输入： ``` 企业版在哪里看每个人的用量明细？ ``` 模型可以一次性输出： ``` { "intent": "usage_detail_query", "need_search": true, "search_query": "企业版 成员 用量明细 查看方式" } ``` 其中，`intent` 是模型从开发者预设的意图类型中选择出来的结果；`need_search` 是模型根据规则判断是否需要检索知识库；`search_query` 是模型对用户问题进行改写后生成的检索关键词。 这样，系统只需要调用一次模型，就能同时获得后续流程所需的信息。后端程序拿到这段 JSON 后，可以根据 need\_search 决定是否检索知识库，再用 search\_query 去查找相关文档，最后将检索结果交给模型生成回答。 > [!NOTE] > > 这里的“一次模型调用”指的是：开发者在同一个 Prompt 中要求模型同时完成意图识别、检索判断和 Query 改写，并以同一个 JSON 返回结果。这样原本需要多次请求模型完成的轻量判断，可以合并为一次请求，从而减少串行调用带来的延迟。 优化后的链路可以变为： ``` 用户输入 ↓ 一次模型调用完成：意图识别 + 是否检索 + Query 改写 ↓ 必要时检索知识库 ↓ 生成最终回答 ``` 这种方式适合意图识别、检索判断、Query 改写、简单分类等轻量任务。对于复杂推理、长文本生成或需要多步判断的任务，则不建议强行合并，以免影响结果质量。 ### 2. 并行处理互不依赖的任务 如果多个任务之间没有强依赖关系，可以并行执行。 例如，在内容生成场景中，可以同时进行： * 敏感词检测 * 用户画像读取 * 知识库检索 * 历史摘要生成 等这些结果都准备好后，再进入最终回答生成环节。这样可以减少用户等待完整链路执行的时间。 ### 3. 用程序逻辑替代简单判断 有些任务并不需要模型完成，例如： * 判断字段是否为空 * 判断用户是否登录 * 判断订单状态是否存在 * 判断金额是否超过阈值 * 固定按钮文案生成 * 标准错误提示返回 这类任务应优先使用规则、函数、数据库查询或缓存完成。模型更适合处理自然语言理解、生成、推理和复杂判断，不应承担所有业务逻辑。 ## 五、使用流式输出降低用户等待感 在交互式场景中，用户感受到的延迟不只是“完整回答生成完毕的时间”，还包括“多久能看到第一段内容”。即使整体生成时间不变，如果用户能更早看到输出开始出现，等待体验也会明显改善。 因此，对于**聊天对话、智能客服、长文本生成、代码生成、Agent 执行**等场景，建议优先使用流式输出。 非流式输出会在模型完成全部生成后一次性返回结果，适合短文本、批处理、后台任务等场景。流式输出则可以在模型生成过程中持续返回内容，让前端实时展示生成结果，更适合实时交互。 例如： ``` { "model": "glm-5.1", "messages": [ { "role": "user", "content": "请帮我总结这篇文章的核心观点" } ], "stream": true } ``` 在前端体验上，也可以结合以下方式进一步降低等待感： * 显示“正在生成” * 实时展示已生成内容 * 对长任务展示阶段性状态 * 工具调用时展示“正在检索”“正在分析”“正在生成” * 对 Agent 多步骤任务展示执行进度 对于复杂任务，用户不一定要求每一步都立即完成，但需要知道任务正在推进。合理的流式输出和状态反馈，可以显著改善应用体验。 ## 六、避免默认使用大模型解决所有问题 大模型适合处理开放式、复杂性高、规则难以穷举的问题，但并不是所有问题都应该交给大模型。为了降低延迟和成本，开发者应优先判断任务是否真的需要模型参与。 以下任务通常可以不用模型完成： * 固定文案返回 * 表单字段校验 * 状态码解释 * 简单规则判断 * 数据库精确查询 * 用户权限判断 * 固定流程引导 * 常见问题的标准答案匹配 例如，用户问“如何修改密码”，如果系统已有标准帮助文档或固定流程，可以直接返回模板答案；只有当用户问题表达复杂、上下文不清晰或需要结合多条信息综合判断时，再交给模型处理。 这种方式不仅可以降低延迟，也能提升系统稳定性，避免模型在简单问题上产生不必要的不确定性。 ## 七、延迟优化检查清单 上线前，可以用以下问题检查应用是否还有优化空间： #### 模型选择 * 是否所有任务都使用了同一个模型？ * 简单分类、改写、抽取任务是否可以使用更轻量的模型？ * 复杂推理任务是否需要开启更强的思考能力？ * 简单任务是否可以关闭不必要的深度思考？ #### 输出控制 * 是否限制了回答长度？ * 是否设置了合理的最大输出 Token 数？ * 是否避免模型生成固定模板内容？ * JSON 字段是否足够简洁？ #### 输入控制 * 是否传入了无关历史对话？ * RAG 检索结果是否过多？ * 是否去除了重复、低相关或无效内容？ * 重复上下文是否可以使用缓存？ #### 调用链路 * 是否存在多个串行模型调用？ * 是否可以合并相近任务？ * 是否可以并行执行互不依赖的步骤？ * 是否有简单规则本可以用程序逻辑完成？ #### 用户体验 * 是否开启流式输出？ * 前端是否展示生成状态？ * 长任务是否展示阶段性进度？ * 工具调用或检索过程是否有反馈？ ## 总结 大模型应用的延迟优化，本质上是在模型能力、响应速度、调用成本和用户体验之间取得平衡。开发者可以结合具体业务链路，优先优化最影响等待体验的环节，让应用响应更快、交互更自然。 # GLM 提示工程指南 Source: https://docs.bigmodel.cn/cn/best-practice/prompt-engineering-general 在 GLM 上可以直接使用的通用提示工程方法：任务描述、上下文组织、输出控制、工具调用与结果验证。 好的提示词并不一定很长。更重要的是让模型理解**要完成什么、需要依据什么、哪些边界不能突破，以及如何判断任务已经完成**。 本指南整理了在 GLM 系列模型上可以尝试的通用提示工程方法，涵盖任务描述、上下文组织、输出控制、长上下文处理、工具使用、多步骤任务执行、长程 Agent 实践与结果验证。内容既适用于日常文本工作，也适用于 Coding、工具调用和 Agent 场景。 这些实践是可以直接使用并通过实际任务检验的**默认起点，而不是固定模板**。不同 GLM 模型在上下文容量、推理能力、工具调用和 API 参数等方面可能存在差异；涉及某一具体版本模型的功能、配置或经过验证的行为特点，应查阅对应的模型指南。本篇不将其他模型的经验直接视为 GLM 的已证实表现。 ## 一、通用原则 ### 1. 清晰、直接地描述任务 明确说明希望模型完成什么。任务越复杂，目标、范围和完成条件越应该具体。 可以把提示交给一位不了解项目背景的同事，请他仅根据提示执行。如果同事会反问“要改哪里、依据什么、做到什么程度、如何判断完成”，模型通常也需要这些信息。 如果希望模型做得更完整、更深入或更简洁，应直接说明，而不是依赖模型从模糊提示中猜测。对 Coding 任务，“超出预期”还应与范围控制平衡：可以要求完整实现和明显边界情况处理，但不应默认允许无关重构或功能扩张。 **效果较差：** ``` 帮我改一下这个项目。 ``` **效果更好：** ``` 修复订单创建接口中的并发问题。 保持现有公开 API 和数据库结构不变。 只修改完成这个问题所必需的代码。 覆盖明显的并发边界情况。 完成后运行现有测试，并说明修改内容和验证结果。 ``` 已知的重要约束尽量尽早提供。如果存在会导致工作内容明显不同的关键歧义，可以先让模型澄清；不必让模型对已经明确的细节反复确认。 ### 2. 提供必要的上下文与限制原因 在目标之外，补充真正影响回答的背景信息，例如任务用途、目标读者、当前情况和必须参考的材料。提供背景的目的是帮助模型理解任务，而不是单纯增加提示词长度。 除了说明“做什么”，还可以解释关键限制背后的原因。原因能帮助模型将规则泛化到未逐条覆盖的情况。 **效果较差：** ``` 不要使用省略号。 ``` **效果更好：** ``` 该回复会被语音合成引擎朗读。省略号可能导致发音不稳定，因此请改写为完整句子。 ``` **效果较差：** ``` 帮我整理一下客户反馈。 ``` **效果更好：** ``` 我们正在为下周的产品评审会整理客户反馈。 请根据下方材料归纳主要问题，合并相似反馈， 并在每个问题后标注对应的原始反馈编号。 不要把推测当成客户已经明确提出的需求。 客户反馈： [粘贴反馈内容] ``` 只提供与判断、执行或输出相关的上下文。如果缺少完成任务所必需的信息，应明确指出信息缺口，而不是凭空补全。 ### 3. 控制任务范围 长程任务给了模型更多调查、修改和优化的空间，也更容易发生范围扩大。任务明确时，应同时说明**要做什么**和**不属于本次工作的内容**。 ``` 完成当前请求所需的工作，并保持在既定范围内。 不要增加未要求的功能，也不要重构与任务无关的代码。 如果发现会实质改变任务范围的问题，再向我确认。 ``` 这里的目标不是限制模型解决问题，而是避免把“可以顺便做”变成“必须一起做”。任务范围和完成条件越明确，越容易评估最终结果。 ### 4. 使用少量有代表性的示例 当文字描述不足以准确表达输出格式、语气、行为边界或分类标准时，可以提供少量有代表性的输入输出示例。 示例应满足三个标准： 1. **相关**：贴近真实输入、真实输出和业务边界； 2. **多样**：覆盖常规情况、边界情况和容易误判的情况； 3. **结构化**：将指令、示例和待处理输入分开，避免示例中的事实被当作当前事实。 对分类、抽取、格式转换等任务，可以从少量示例开始；示例数量不是目标，覆盖关键差异才是目标。不要为了追求数量而堆叠相似样本。 **效果较差：** ``` 汇报要简洁。 ``` **效果更好：** ``` 问题：修改是否完成？ 期望回答： 已完成。修改了 2 个文件，相关测试全部通过；未进行生产环境验证。 ``` 示例中的事实和数字只表示期望的表达形式，实际汇报仍必须依据本轮真实执行结果。 ### 5. 给复杂提示建立清晰结构 当提示同时包含任务要求、背景、参考资料、示例和输出约束时，可以使用分段结构把不同内容区分开，避免指令与待处理数据混在一起。 Markdown 标题、编号列表、语义标签和 XML 风格标签都可以用于组织提示。选择一种清晰、一致的方式即可，不必为了形式增加过多层级。 **Markdown 结构示例：** ```markdown theme={null} ## 任务 根据用户反馈归纳需要改进的问题。 ## 背景 结果用于产品评审会，重点突出反复出现的问题。 ## 输入材料 [粘贴用户反馈] ## 输出要求 输出“问题类别、主要表现、对应反馈编号”三列。 无法由材料支持的结论请标为“待核实”。 ``` **XML 风格结构示例：** 当提示混合指令、上下文、多个文档和用户输入时，XML 风格标签可以更明确地区分内容边界： ```xml theme={null} 根据用户反馈归纳需要改进的问题，合并相似反馈。 结果用于产品评审会，重点突出反复出现的问题。 用户反馈.txt [粘贴用户反馈] 输出“问题类别、主要表现、对应反馈编号”三列。 无法由材料支持的结论请标为“待核实”。 ``` 标签名应描述内容用途，并在同一系统或同一任务中保持一致。XML 标签是清晰的分隔手段，但不应被描述为对所有 GLM 版本都必然优于 Markdown；是否更合适，应在自己的任务上比较。 重点是让模型区分**需要遵守的要求**和**需要处理的材料**。外部文档、网页、工具结果和用户提交的数据应当作为信息来源，而不应因为其中出现了指令式语句，就被自动当作新的任务要求。 ### 6. 合理设置角色与职责 当任务需要特定的专业视角、受众意识或工作职责时，可以用简洁的描述说明模型应该承担什么角色、根据什么标准工作。 ``` 你负责对技术文档进行可读性审查。 读者是刚接触大模型开发的工程师。 请指出术语未解释、步骤不完整和示例不清晰的地方， 并提出具体修改建议；不要替作者虚构技术事实。 ``` 角色设定应服务于任务，不必堆叠“世界顶级专家”等夸张身份。角色不能代替具体任务说明、原始证据和验证标准。也不要让模型声称自己具有与实际运行环境不符的身份、权限或专业资格。 ## 二、输出与格式 ### 1. 明确期望的输出 如果对回答的内容、结构或先后顺序有要求，直接说明。相较于“回答专业一些”，能够检查的要求通常更容易执行。 ``` 第一句话给出结论。 然后说明： 1. 修改了什么； 2. 如何验证； 3. 哪些内容仍未验证。 ``` 要求输出表格、清单或分步骤说明时，可以明确字段、排序原则以及缺失信息的处理方式。如果没有特别的格式需求，不必为简单问答强制设计复杂结构。 ### 2. 正向描述输出格式 优先告诉模型应输出什么，而不是只列禁止项。正向描述能减少歧义，也便于后续检查。 **效果较差：** ``` 不要使用 Markdown。 ``` **效果更好：** ``` 请输出连贯段落，仅在代码和必要标题处使用 Markdown。 ``` **效果较差：** ``` 不要太啰嗦。 ``` **效果更好：** ``` 先用一句话给出结论，再用不超过五条要点说明依据、已验证事项和未验证事项。 ``` 提示的组织方式也可能影响输出风格。如果希望输出简洁、直接、结构清晰，提示本身也应避免冗长堆叠和模糊修辞。 ### 3. 使用结构化输出约束机器可读结果 当模型输出还需要被程序继续处理时，应明确规定数据结构、字段含义和取值约束，而不是只写“返回 JSON”。 ``` 请把发现的问题输出为 JSON 数组，每个元素包含： - issue：问题名称，字符串 - file：相关文件路径，字符串 - severity：严重程度，只能为 high、medium、low - description：问题说明，字符串 没有发现问题时返回空数组 []。 不要在 JSON 前后附加解释文字。 ``` > [!TIP] > > 结构化提示能够描述期望的结果，但不能保证返回数据始终合法。如果下游程序依赖该结果，应用侧仍应检查能否解析、字段是否完整、类型与取值是否正确，以及是否满足业务约束。模型特定的结构化输出 API 配置不属于本篇范围。 ### 4. 控制回答长度与信息密度 输出控制不只是让内容更短，还包括保留必要信息、避免重复，以及让答案适合实际使用场景。 ``` 覆盖完成任务所需的实质内容。 避免重复摘要、模板化填充和与任务无关的扩展。 ``` 如果需要详细教程，可以要求解释关键概念、操作步骤和判断标准；如果只需要结果汇报，可以约束为结论、依据和未完成事项。 对报告、演示稿或可视化文档，应明确受众、结构、设计约束和交付格式。不要只写“做得好看”或“专业一些”。 ## 三、上下文与信息处理 ### 1. 组织长文档和多来源信息 处理长文档或多份资料时，先明确**材料边界和来源**，再告诉模型要查找、比较或提取什么内容。不同资料中的事实与结论不要混在一起。 建议为每份材料标注： * 来源； * 时间； * 版本； * 适用范围； * 可信度或权威性，如果会影响判断； * 是否为不可信用户输入或工具返回结果。 **多文档比较示例：** ```xml theme={null} 请比较下面两份方案，只分析三个方面： 实验目标、评价指标、风险控制。 输出差异表，并在每条差异后标明资料来源。 如果某份资料没有提到相关内容，请写“原文未说明”，不要补写。 方案A.md [粘贴资料 A] 方案B.md [粘贴资料 B] ``` 当材料特别长时，可以先定位相关部分、记录出处，再开展归纳和比较。建议： 1. 先查找与问题直接相关的段落； 2. 为每条结论保留来源或原文位置； 3. 区分“原文明确支持”“合理推断”“外部知识”“无法确认”； 4. 对冲突信息不要强行合并，应说明冲突及来源； 5. 材料超过上下文或预算时，使用检索、分批摘要或局部读取； 6. 验证关键段落确实进入了上下文。 长材料的布局可以作为实验变量，例如材料前置、查询前置、分段检索后局部引用。不同模型和任务类型的最优布局可能不同，应以自己的 GLM 任务评测结果为准，不直接沿用其他模型的结论。 ### 2. 基于原始资料回答，区分事实与推测 对于代码库、文档、数据和其他已有材料，应尽量基于真实内容回答，而不是只根据文件名、记忆或用户概述猜测实现细节。 ``` 先检查与问题直接相关的原始资料。 根据实际内容给出结论，并说明关键依据。 没有检查到或无法确认的内容，请明确说明，不要猜测。 ``` 对于 Coding 任务，可以进一步明确： ``` 回答前先读取与问题直接相关的文件。 基于实际代码说明结论。 没有检查到的实现不要猜测。 ``` 修改代码前也应先了解相关实现、调用关系和约束，再决定如何修改。必要时将信息分为： * **已确认的事实**：来自当前代码、日志、测试或权威材料； * **合理推断**：有依据但尚未直接验证； * **尚待验证**：缺少证据或存在冲突。 工具返回失败时，不要把预期结果当作已发生结果。 ### 3. 研究与信息收集 研究型任务应先定义成功标准：需要回答什么、可接受来源是什么、时间范围是什么、是否要求交叉验证、结论需要达到什么确定程度。 执行中可以： 1. 维护多个竞争假设； 2. 为每个假设记录支持证据和反对证据； 3. 对高风险或事实敏感结论进行多来源验证； 4. 保留来源链接或文档位置； 5. 输出时区分事实、推断和不确定项。 不要把单一检索摘要、单一模型回答或未经验证的二手转述当作最终事实。 ## 四、工具使用 ### 1. 说明工具为什么以及何时使用 工具描述不应只有名称和参数，还应让模型知道工具解决什么问题、何时需要调用，以及什么情况下不应该调用。 ``` 当用户询问具体订单的支付、发货或物流状态时， 先调用订单查询工具获取最新数据。 如果用户询问的是通用退货规则， 不需要调用订单查询工具。 ``` 如果多个工具的职责相近，应明确调用边界。比如“查询订单详情”和“查询物流轨迹”分别负责什么、各自需要哪些输入，以及哪个结果可以作为后续操作的依据。 工具能否真正被调用，取决于应用是否提供相应能力和权限。提示词不能替代实际的工具配置、权限检查与执行结果校验。 ### 2. 区分建议、研究和执行 用户说“你能建议一些修改吗”和“请修改这段代码”对应不同的行动意图。前者通常要求分析，后者允许执行。对于会读取文件、修改代码、访问外部系统或产生副作用的场景，应在系统提示中明确默认行为。 **主动诊断模式：** ```xml theme={null} 当用户明确要求检查、修改或完成工作时，执行必要且安全的本地工具调用。 缺少非敏感信息时，先读取相关文件或调用查询工具确认，不要猜测参数。 影响外部系统或难以回滚的操作仍需确认。 ``` **保守分析模式：** ```xml theme={null} 默认只分析和给出建议，不修改文件或改变系统状态。 只有用户明确授权后，才执行读取、编辑或外部调用。 ``` 两种模式没有绝对优劣。开发环境、诊断任务和自动化 Agent 更适合主动模式；法律、医疗、财务、共享系统、生产环境或高风险决策更适合保守模式。 ### 3. 并行处理相互独立的工具调用 当多个工具调用相互独立，且执行环境支持并行调用时，可以考虑并行执行以减少等待。后续步骤若依赖前一步的结果，则应按依赖顺序执行。 **最大并行模式：** ```xml theme={null} 如果多个工具调用相互独立，应在同一轮并行执行。 如果后续调用的参数依赖前序结果，必须等待结果。 不要猜测缺失参数。 ``` **顺序执行模式：** ```xml theme={null} 为保证稳定性，按列出顺序执行工具调用。 仅确认没有状态竞争、资源冲突或副作用时才并行。 ``` 例如，分别读取两份独立文档可以并行；先查询订单编号，再用返回的物流单号查询快递，则存在先后依赖。 并行不是无条件更好。大量 Shell 命令、共享资源、限流 API 或有状态工具可能因过度并行降低稳定性。对于工具调用较少的简单任务，通常不需要专门强调并行策略。 ### 4. 处理工具失败与结果校验 工具调用结果不应只因调用成功就被默认可信。应用侧和模型都应关注： * 调用是否失败、超时或返回部分结果； * 返回数据是否满足 schema 和业务约束； * 是否是缓存、旧版本或错误来源； * 是否需要重试，以及重试是否安全； * 有副作用的操作是否已经实际生效。 对有外部副作用的调用，不应在结果未知时报告“已完成”。重试前应确认操作是否幂等，避免重复下单、重复发送消息或重复修改共享状态。 ## 五、思考与任务执行 ### 1. 根据任务复杂度调整处理策略 复杂 Coding、多步骤规划和长程 Agent 任务通常需要更充分地理解约束、分析依赖并检查结果。简单、重复或对延迟敏感的任务则更应关注执行效率。 如果具体模型支持推理强度等配置，应结合版本文档与实际评测选择。通用篇不规定某一模型的参数取值。 不要默认认为推理步骤越多，答案就一定越好。可以在自己的任务集上比较： * **任务完成质量**：是否满足需求、是否出现遗漏或事实错误； * **Token 消耗**：完成同一任务需要多少资源； * **响应时间**：能否满足实际使用场景的延迟要求。 ### 2. 避免过度规划与泛化检查 当信息充分、目标确定时，不必反复推导已确认的事实，也不必持续复议已经作出的选择。 ``` 信息足够时开始执行。 已经确认的事实和决定无需反复重新讨论。 如果没有新的信息推翻当前方案，就沿当前方案继续推进。 ``` 重点不是减少必要思考，而是让思考服务于下一步行动。 在已经有明确验证步骤的任务中，连续加入“再仔细检查一次”“一定要确认没有问题”等重复要求，不一定比给出具体检查项更有效。 ``` 完成后确认： - 相关测试是否通过； - 是否修改了任务范围外的文件； - 是否仍存在未经验证的假设。 ``` 有具体检查目标，模型才能更清楚地判断何时完成，以及哪些问题需要继续处理。 ### 3. 避免过度工程 最小正确实现优先。不要为了展示完整性而引入不必要的复杂度。 应注意： * 不为一次性逻辑创建抽象； * 不修改与任务无关的文档、类型或格式； * 不为不可能发生的输入添加防御分支； * 错误处理和输入校验应集中在系统边界，例如用户输入、外部 API、文件解析和网络响应； * 不设计假想的未来需求； * 复杂度以解决当前问题所需的最小量为宜。 如果复杂度是解决问题所必需的，应在汇报中解释原因，而不是为了避免复杂度而牺牲正确性。 ## 六、长程 Agent 实践 ### 1. 持续维护任务状态 对于跨多步骤、长时间运行的任务，应保留当前目标、已经完成的工作、关键决定和剩余事项，避免上下文变化后重复劳动或遗漏约束。 可以使用两类状态记录： * **自由格式进度笔记**：例如 `progress.md`，记录总体进展、关键决策、阻塞和下一步； * **结构化状态数据**：例如 `tasks.json` 或 `tests.json`，记录任务、测试、验证结果和依赖关系。 建议记录： * 当前目标； * 已完成的重要工作； * 已确认的决定及原因； * 尚未完成或待验证的事项； * 关键文件、命令、日志或来源。 不要把代码库中已有的信息大段重复复制进状态文件；旧信息失效后应更新或删除。状态文件只有在被实际保存、读取和维护时才能发挥作用，不能仅凭提示词假设模型会自动保留跨会话状态。 ### 2. 跨上下文恢复 长任务可能跨越多个上下文窗口、会话或执行环境。恢复任务时，应先重建状态，再继续实现。 可以要求： ``` 确认工作目录和权限。 读取 progress.md、tasks.json 和 git 状态。 运行基础测试或检查脚本。 核对原始目标、已完成事项和未完成事项。 再继续实现新改动。 ``` 对于大型任务，可以准备初始化脚本，用于安装依赖、启动服务、运行基础测试或生成必要环境，减少新上下文中的重复准备工作。 如果使用 git，应利用提交、分支和变更记录作为状态检查点。不要把未解释的无关变更混入任务提交。 ### 3. 平衡自主性与安全边界 本地、可逆、低风险操作可以直接执行，例如读取文件、编辑工作区文件、运行测试。以下操作应先确认或遵循平台权限： * 删除数据、重置分支或清空数据库； * 强制推送、改写已发布历史； * 修改共享基础设施； * 向外部服务发送消息或提交表单； * 创建持久凭据或修改权限； * 安装软件； * 任何难以回滚、影响生产系统或影响他人的操作。 遇到障碍时，不应使用破坏性捷径绕过验证或安全检查。提示词可以声明风险偏好，但不能替代应用侧权限控制、审计和人工审批。 ### 4. 避免不必要的委派 子智能体适合处理真正独立、能够并行执行或需要隔离上下文的任务。对于几次工具调用即可完成的连续工作，没有必要只为使用“多 Agent”而额外拆分。 适合委派的情况： * 子任务真正独立； * 可并行执行； * 需要隔离上下文； * 需要不同专业工具或独立复核。 不适合委派的情况： * 连续几步就能完成； * 各步骤强依赖同一上下文； * 单文件修改； * 交接和整合成本高于并行收益； * 用户未授权额外 Agent 或权限。 委派结果应回传明确结论、修改文件、验证证据和剩余问题，不能只回传模糊总结。使用多个 Agent 不应被视为结果一定更好的保证。 ### 5. 使用复杂提示链 当单次调用难以保证质量，或需要在中间结果上人工审查时，可以使用提示链： ```text theme={null} 生成草案 → 对照标准审查 → 最小必要修改 → 程序化验证 ``` 每一步可以单独记录、评估或分支。常见模式是自我纠正：先让模型生成草案，再用明确标准独立审查，最后根据审查结果修改。 提示链的价值是可控和可观察，不是越长越好。对简单任务，拆链会增加成本和错误传递风险。 ### 6. 管理临时文件 Coding Agent 可以为验证创建临时脚本、夹具或输出文件。这是合理行为，但如果用户要求最小变更或干净工作区，应明确清理策略： ``` 为迭代创建的临时脚本、生成物和辅助文件，任务结束前应清理或集中说明。 不要把调试代码、无关重构或一次性脚本遗留在最终变更中。 ``` 不要为了减少文件数量而跳过必要的测试脚本或验证产物；应在“可验证性”和“最小变更”之间根据任务要求平衡。 ## 七、验证与持续优化 ### 1. 根据实际结果进行验证与汇报 任务完成与否，应以实际产物和验证证据为依据，而不是依据计划、推测或模型自己的口头承诺。 ``` 汇报进度前，先核对本轮实际执行结果。 已经验证的内容直接说明结果。 尚未验证的内容明确标记为未验证。 ``` 如果需要中间更新，只在发现重要信息、改变方向或完成关键阶段时简要汇报即可。最终汇报优先回答“结果是什么”，再补充过程和证据。 ### 2. 让实现解决真实问题，而不是只适配测试 测试是验证实现的方法，而不是实现目标本身。 ``` 实现应解决实际问题，并对合法输入保持正确。 不要通过硬编码测试数据或只针对当前测试用例的特殊分支来通过测试。 ``` 不要修改或绕过测试来制造“通过”的结果。如果测试与需求明显冲突，应指出冲突并请求确认。 ### 3. 对重要结果进行独立复核 对于高价值、风险较高或容易遗漏问题的任务，可以考虑用新的独立上下文复核结果。 ``` 请独立检查当前结果是否满足原始要求。 重点寻找遗漏、未经验证的假设和与任务范围不一致的修改。 不要默认接受已有结论。 ``` 独立复核可能发现新的问题，但不意味着它一定优于常规自检。是否增加复核，应根据任务风险、成本和实际评测决定。 ### 4. 通过评测持续优化提示词 一次提示词有效，不代表它面对不同输入时都有效。更可靠的优化方式是先明确成功标准，再使用覆盖常见情况和边界情况的样本，比较修改前后的表现。 建议记录： * **质量指标**：任务完成率、事实错误、遗漏等； * **格式指标**：结构化输出是否合法、字段是否正确； * **执行指标**：工具调用是否合理、是否完成必要验证； * **效率指标**：响应时间、Token 消耗或调用成本； * **安全指标**：高风险操作确认率、越权操作次数。 评测样本可以拆分为： * **开发集**：用于迭代提示； * **保留集**：不参与日常调参，用于回归验证； * **边界集**：长输入、空输入、冲突来源、注入攻击、工具失败； * **人工评审集**：用于质量、安全和用户体验评估。 ``` 请对照以下成功标准检查本次输出： 1. 是否覆盖用户要求的全部字段； 2. 是否存在无法由原始材料支持的结论； 3. 输出能否被下游程序正常解析。 先报告不符合项，再给出最小必要的修改建议。 ``` 模型自检可以辅助定位问题，但不应代替程序校验、人工复核或独立评测数据。具体指标、阈值和样本量，应由真实业务要求决定。 ## 八、从其他模型提示迁移到 GLM 从其他模型迁移提示时，不要只替换模型名称。建议检查： 1. **删除模型专属参数**：不保留其他模型的思考、effort、预填充、工具批处理或其他 API 专属配置。GLM 应使用对应版本文档支持的参数。 2. **收敛过度触发提示**：旧提示中的“必须始终使用某工具”“如有疑问就多检查”可能导致过度调用或过度验证。改成具体触发条件和停止条件。 3. **重写身份与角色**：删除其他模型身份设定。角色只描述职责、读者和标准，不虚构专业等级或权限。 4. **调整结构标记**：Markdown、语义标签和 XML 风格标签都可以保留，但应在 GLM 任务上比较效果。 5. **检查长上下文布局**：比较材料前置、查询前置、分段检索和局部引用，而不是直接沿用其他模型的最优布局结论。 6. **加强验证**：JSON 输出必须程序化校验；Coding 任务必须运行可行测试；研究任务必须保留来源和不确定度。 7. **记录版本**：提示词变更、模型版本、参数、评测集和结果应一起记录，避免把版本差异误判为提示词效果。 ## 九、综合示例 ### 1. 普通文档处理任务 ```markdown theme={null} ## 任务 阅读给定的研究方案，整理出“研究问题、实验步骤、评价指标”。 ## 背景 这份总结将用于向不熟悉项目的同事介绍实验。 ## 材料 [粘贴方案原文] ## 要求 1. 使用通俗中文，但保留原文的重要技术术语。 2. 每项结论标出对应的原文依据。 3. 对原文没有说明的信息标记“未说明”。 4. 不设计原文之外的新实验。 ## 输出 先给一段简述，再给出结构化表格。 ``` 这个示例组合了任务目标、受众背景、材料边界、证据要求和输出格式，适合总结报告、分析资料或比较方案等工作。 ### 2. 长程 Coding 任务 ``` 你负责完成当前代码任务。 先读取与问题直接相关的文件，基于实际实现再开始修改。 完成当前请求所需的全部工作，并保持在既定范围内。 不要增加未要求的功能，也不要重构无关代码。 如果存在会明显改变工作范围的关键歧义，再向我确认。 实现应解决真实问题，而不是只针对现有测试用例。 相互独立的工具调用可以并行； 存在结果依赖时按顺序执行，不要猜测缺失参数。 如果创建临时脚本或生成物，任务结束前应清理或说明。 完成后根据实际执行结果汇报： 先说明结果，再说明修改内容、验证情况和仍未验证的事项。 ``` 这个示例更适用于能够读取文件、修改代码和运行测试的开发环境。实际使用时，还应填入具体任务、项目约束和验收条件，不能把上述通用指令当成完整需求。 ## 十、版本与验证说明 本篇只覆盖通用提示方法，不规定某一 GLM 模型的上下文长度、思考强度、采样参数、结构化输出 API 或版本专属能力。具体配置应以使用时的 GLM 官方文档为准。 > [!TIP] > > 本版新增的 XML 分区、正向格式约束、多来源证据判断和主动/保守工具模式，已在 GLM 代理环境中完成单次冒烟测试，行为符合预期。冒烟测试不是统计基准；生产使用前仍应在自己的任务集和 GLM 版本上评测。 好的提示词不需要一次写入所有技巧。更实用的做法是：**把目标说清楚，提供真正需要的上下文，明确关键约束与验证方式，再根据实际任务的结果持续迭代。** # 一键安装助手 Source: https://docs.bigmodel.cn/cn/coding-plan/extension/coding-tool-helper 为 GLM Coding Plan 用户统一管理与配置 Claude Code 等 CLI 工具的命令行助手 **NPM 包地址**: [@z\_ai/coding-helper](https://www.npmjs.com/package/@z_ai/coding-helper) \ **前提条件**: [Node.js >= v18.0.0](https://nodejs.org/en/download/) ## 工具简介 Coding Tool Helper （一键安装小助手）是一个编码工具助手，快速将您的 **GLM 编码套餐**加载到您喜爱的**编码工具**中。安装并运行它，按照界面提示操作即可自动完成工具安装，套餐配置，MCP 服务器管理，Claude Code 插件市场等。 当前编码工具支持： * **Claude Code** * **Codex** * **OpenCode** * **Crush** * **Factory Droid** 当前插件市场支持: * [用量查询插件](/cn/coding-plan/extension/usage-query-plugin) * [问题反馈插件](/cn/coding-plan/extension/bug-feedback-plugin) ## 功能特性 > **交互式向导** > > 友好的设置引导 > **套餐集成** > > 将 GLM 套餐接入喜爱的编码工具 > **工具管理** > > 自动检测、安装和配置编码工具 > **MCP 配置** > > 轻松管理 MCP 服务 > **插件市场** > > 内置 Claude Code 插件市场 > **国际化支持** > > 界面支持中文等多语言 ## 快速开始 **1. 获取 API Key** * 个人版套餐（或领取体验卡）的用户，通过 [个人编程套餐 > 套餐概览](https://bigmodel.cn/apikey/coding-plan-per)，新建 API Key * 团队版套餐的成员，通过 [团队编程套餐 > 我的套餐](https://bigmodel.cn/apikey/coding-plan-team)，新建 API Key **2. 安装 Node.js** 如果您尚未安装 Node.js，请前往 [Node.js 官网](https://nodejs.org/en/download/) 下载并安装最新的 LTS 版本。\ macOS 用户注意：推荐使用 `nvm` 工具安装 Node.js，避免权限问题，进入 [Node.js 官网](https://nodejs.org/en/download/) 如下在命令行粘贴运行即可。 ![Description](https://cdn.bigmodel.cn/markdown/1765856965981image.png?attname=image.png) > [!TIP] > > macOS 用户若您已使用其它方式安装 Node.js，在后续执行命令过程若遇到 Permission 权限问题，需要在命令前加 `sudo` 来提高权限运行，或者卸载后改用 `nvm` 重新安装。 **3. 安装启动** 前提条件：您需要安装 [Node.js 18+ 或更新版本](https://nodejs.org/en/download/) \ 选择下面的任意一种安装启动方式 **方式一（推荐：npx 即用）** 该方式适合偶尔使用 Coding Tool Helper 的用户，无需全局安装，直接通过 npx 运行即可启动工具。 ```shell theme={null} ## 进入命令行界面，执行如下运行 Coding Tool Helper npx @z_ai/coding-helper ``` **方式二（全局安装重复使用）** 该方式适合频繁使用 Coding Tool Helper 的用户，通过全局安装后可运行 `coding-helper` 或 `chelper` 命令启动工具。 > [!TIP] > > 若您执行 `npm install` 后报错提示权限不足 `permission denied`，请尝试在命令前加上 sudo（macOS / Linux），或以管理员身份运行命令行（Windows）。\ > 如: `sudo npm install -g @z_ai/coding-helper` \ > 或推荐使用 npx 方式直接启动 `npx @z_ai/coding-helper` ```shell theme={null} ## 进入命令行界面，先全局安装 @z_ai/coding-helper npm install -g @z_ai/coding-helper ## 然后运行 coding-helper 或 chelper coding-helper ``` **4. 完成引导** 进入向导界面后，通过键盘上下方向键选择，回车确认按钮，根据引导进行配置。\ 向导将引导您完成：\ 选择界面语言 --> 选择编码套餐 --> 输入 API 密钥 --> 选择要管理的工具 \ \--> 自动安装工具（如需要） --> 进入工具管理菜单 --> 装载编码套餐到工具 \ \--> 管理 MCP 服务（可选） --> 完整配置，启动编码工具 ## 其它相关 ### 命令列表 > 除了支持交互式向导外，Coding Tool Helper 还支持通过命令行 `coding-helper` 或 `chelper` 加参数直接执行各项功能： ```bash theme={null} # 运行初始化向导 coding-helper init # 语言管理 coding-helper lang show # 显示当前语言 coding-helper lang set zh_CN # 设置为中文 coding-helper lang --help # 查看语言命令帮助 # API 密钥管理 coding-helper auth # 交互式设置密钥 coding-helper auth glm_coding_plan_china # 直接选择 China 套餐并设置密钥 coding-helper auth revoke # 删除已保存的密钥 coding-helper auth reload claude # 将最新套餐信息加载至Claude Code工具 coding-helper auth --help # 查看认证命令帮助 coding-helper doctor # 检查系统配置和工具状态 coding-helper --help # 显示帮助信息 coding-helper --version # 显示版本 ``` ### 问题排查 遇到问题可以先使用 `coding-helper doctor` 命令进行健康检查，排查常见问题。 > **网络错误，请检查网络连接** > > **问题：** 保存校验 API KEY 或其它网络操作时，报错 Network Error 等网络错误 > > **解决方案：** > > 1. 请检查网络链接或配置代理 > 2. 注意若您需使用代理才能访问外部网络，NodeJs 程序本身并不会自动使用系统代理配置，请配置环境变量 `HTTP_PROXY` 和 `HTTPS_PROXY` 来让 NodeJs 使用代理 > > ```shell theme={null} > # 参考如下 > export HTTP_PROXY=http://your.proxy.server:port > export HTTPS_PROXY=http://your.proxy.server:port > ``` > **网络超时** > > **问题：** 运行或安装编码工具时，报错 timeout 等网络超时 > > **解决方案：** > > 1. 请检查网络链接或配置代理 > 2. 或切换NPM源为国内源 > **Factory Droid 安装失败** > > **问题：** 运行安装 Factory Droid 后，执行 `droid` 命令报错 command not found > > **解决方案：** > > 1. 请留意安装过程结束后的信息，根据环境有可能需要手动将 Factory Droid 可执行文件路径添加到系统 PATH 中 > **Claude Code 插件市场里插件状态不对** > > **问题：** 使用 Claude Code 插件市场时，发现插件状态不对，如显示未安装但实际上已安装等 > > **解决方案：** > > 1. 请执行 `claude update` 升级 Claude Code 至最新版本, 2.0.70+ > **权限不足 EACCES: permission denied** > > **问题：** 运行 npm install -g 报错 EACCES: permission denied 权限不足 > > **解决方案：** > > 1. 使用 sudo 提升权限后重试（macOS / Linux） > 2. 以管理员身份运行命令行（Windows） > 3. 使用 npx 方式直接启动 `npx @z_ai/coding-helper` > 4. 推荐使用 nvm 工具管理 Node.js 版本，避免全局权限问题 > **API Key 无效** > > **问题：** 收到 API Key 无效的错误 > > **解决方案：** > > 1. 确认 API Key 是否正确复制 > 2. 检查 API Key 对应账户是否有足够的余额 > **连接超时** > > **问题：** 服务连接超时 > > **解决方案：** > > 1. 检查网络连接 > 2. 确认防火墙设置 > 3. 确认 Node.js 与网络环境已就绪 # GLM in Excel（Beta） Source: https://docs.bigmodel.cn/cn/coding-plan/extension/glm-in-excel ## 产品概述 GLM in Excel 是适配 Excel 官方的 AI 插件，以侧边栏集成和展示，通过自然语言交互赋能表格工作流，实现 **数据解释、公式生成、图表可视化、公式错误检测与修复、跨sheet 页查询** 等任务的自动化执行。 核心由 GLM-5 模型、Agent SDK/Agent loop、Skills等模块驱动，适配 Microsoft 365 的 Excel 环境，其核心交互与能力如下： * **自然语言驱动**：在侧边栏输入指令（如 “制作可视化图表”“修复 #REF! 错误”），GLM 直接解析并操作表格，生成可追溯的单元格级引用。 * **闭环执行流程**：Agent 拆解任务 → 调用相应的 tools → Agent Loop 校验结果 → 在 Excel 中直接修改并高亮变更，全程不离开表格环境 > [!TIP] > > GLM in Excel 插件目前仅支持 GLM-5 配置及调用。