主题
模型管理
用户端能选哪些对话模型，取决于模型管理。这里至少要配置一个可用模型，否则用户无法正常发起对话，Agent 也无法执行任何工具。
- 后台入口：AI 能力 / 模型管理
列表字段
| 字段 | 说明 |
|---|---|
| 排序 | 控制模型在前台或后台列表中的展示顺序 |
| 模型名称 | 给用户看的名称，例如 GPT-4.1、DeepSeek |
| 绑定模型 | 实际发送给模型服务商的模型 ID |
| 多模态 | 标记模型是否支持图片、PDF 文档、视频、音频理解 |
| 调用次数 | 当前模型累计调用次数 |
| 已用 Token | 当前模型累计使用 Token |
| 状态 | 控制模型是否可用 |
新增模型
点击“添加模型”，进入模型表单。
基础信息
| 配置项 | 说明 | 建议 |
|---|---|---|
| 状态 | 是否启用该模型 | 测试通过后再开启 |
| 排序 | 展示顺序，数字越小越靠前 | 常用模型填更小的数字 |
| 模型名称 | 展示给用户看的模型名称 | 使用清晰名称，不要只写代号 |
| 模型简介 | 简短描述模型特点 | 说明它更适合处理哪类任务 |
| 模型图标 | 模型头像或图标地址 | 可上传 PNG、JPG、WebP、ICO、SVG |
| 调用频率 | 每小时允许调用次数 | 免费或高成本模型建议适当收紧 |
| 计费系数 | 每次对话消耗的积分 | 和套餐价格、模型成本一起评估 |
| Token 计费 | 是否按 Token 计费 | 成本波动大的模型建议开启 |
| 计费比例 | 每多少 Token 扣一次积分 | 只在 Token 计费开启时生效 |
计费系数、Token 计费、计费比例只有装载商业包时才产生扣费，没有商业包的站点这三项不影响调用。
API 配置
| 配置项 | 用途 | 从哪里找 | 示例 |
|---|---|---|---|
| 供应商模板 | 选择常见服务商后自动填充调用协议、基础地址和模型 | 后台下拉选择 | 可选；没有合适模板时手动填写下方字段 |
| 调用协议 | 决定后端按哪种接口协议组装请求 | 后台选择 | 下拉只列出当前部署已装载的协议：内核自带 OpenAI Chat Completions / 兼容接口，扩展包提供 OpenAI Responses、Anthropic Messages、Gemini GenerateContent 与 OpenCode Go，按服务商实际能力选择 |
| 绑定模型 | 实际发送给模型服务商的模型 ID | 服务商模型文档或后台模型列表 | gpt-4.1、deepseek-chat |
| API Key | 模型服务商提供的调用密钥 | 服务商控制台的 API Keys、API-KEY 管理或访问凭证页面 | sk-... |
| 基础地址 | 服务商接口的基础地址，可以带代理前缀或版本段（如 /v1、/v4） | 服务商 API 文档中的 Base URL / Endpoint | https://api.example.com |
| Endpoint Path | 接在基础地址后的请求路径 | 服务商接口文档 | 留空时按调用协议使用默认端点路径（见下方），大多数服务可留空 |
实际请求地址 = 基础地址 + 端点路径。Endpoint Path 留空时按调用协议使用默认端点路径：
| 调用协议 | 默认端点路径 | 基础地址为 https://api.example.com 时的请求地址 |
|---|---|---|
| OpenAI Chat Completions / 兼容接口、OpenCode Go | /v1/chat/completions | https://api.example.com/v1/chat/completions |
| OpenAI Responses | /v1/responses | https://api.example.com/v1/responses |
| Anthropic Messages | /v1/messages | https://api.example.com/v1/messages |
| Gemini GenerateContent | 非流式 /v1beta/models/{模型}:generateContent；流式 /v1beta/models/{模型}:streamGenerateContent，并带 ?alt=sse | https://api.example.com/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse（流式） |
拼接规则：
- 基础地址以版本段结尾（
/v1、/v4、/v1beta这类）时，不再重复默认端点路径里的版本段：例如https://open.bigmodel.cn/api/coding/paas/v4的请求地址是https://open.bigmodel.cn/api/coding/paas/v4/chat/completions。服务商接口是/api/v3/chat/completions、/compatible-mode/v1/chat/completions这类路径时，把基础地址填到版本段即可。 - 基础地址里的代理前缀会保留：
https://proxy.example.com/api/llm/openai的请求地址是https://proxy.example.com/api/llm/openai/v1/chat/completions。 - 基础地址已经是完整端点（以
/chat/completions、/responses、/messages、:generateContent等结尾）时直接使用、不再拼接；这时不要再填写 Endpoint Path，否则地址预览或实际调用时会报错（保存本身不拦截）。
填写基础地址和 API Key 后，后台会尝试读取服务商的远程模型列表。读取到远程模型时，“绑定模型”只显示远程返回的模型；没有读取到远程模型时，才回退显示系统内置预设模型，也可以手动输入模型 ID。
常见模型服务商入口
| 服务商 | API Key 获取位置 | 基础地址示例 | 备注 |
|---|---|---|---|
| OpenAI | OpenAI Platform → API keys | https://api.openai.com/v1 | 只在服务端填写，前端和公开文档不要暴露 |
| DeepSeek | DeepSeek Platform → API keys | https://api.deepseek.com | 系统会自动补 /v1，也可按服务商文档填写完整兼容地址 |
| 阿里云百炼 / 通义千问 | 阿里云百炼控制台 → API-KEY 管理 | https://dashscope.aliyuncs.com/compatible-mode/v1 | 不同地域可能有不同兼容地址，以百炼控制台和文档为准 |
| 火山方舟 / 豆包 | 火山方舟控制台 → API Key 管理 | https://ark.cn-beijing.volces.com/api/v3 | 模型 ID 通常使用方舟推理接入点或模型名称 |
| OpenCode Go | OpenCode Go 文档 | https://opencode.ai/zen/go | 选择“OpenCode Go”供应商模板或 OpenCode Go Chat Completions 协议；系统自动添加所需请求头，不要改用普通兼容协议 |
| 自建网关 / 代理 | 你的网关管理后台 | https://llm.example.com/v1 | 确认网关兼容 OpenAI Chat Completions 协议 |
如果服务商文档给出的地址已经包含 /v1、/api/v3 或其他版本号，按服务商原文填写即可。不同服务商的模型 ID、计费和多模态能力不一样，添加后建议先用“真实探针”自动验证文本、当前协议可发送的多模态能力和全部推理档位。
多模态、推理强度和上下文
“多模态支持”和“推理强度”都应按模型实际能力勾选；“上下文长度”单独填写。
| 配置项 | 说明 |
|---|---|
| 多模态支持：图片解析 | 允许模型读取图片 |
| 多模态支持：PDF 文档 | 允许模型读取 PDF 文档 |
| 多模态支持：视频解析 | 允许模型读取视频 |
| 多模态支持：音频解析 | 允许模型读取音频 |
| 推理强度 | 决定用户端可选择哪些思考档位 |
| 默认强度 | 用户首次使用或原档位不适用于新模型时采用的档位 |
| 上下文长度 | 模型可接受的上下文长度 |
点击“真实探针”后，系统会先明确提示最多请求次数；管理员确认后，才会向当前模型发送文本、当前协议能够发送的所有图片、文档、视频或音频探针，并检查“关闭”到“最高”的全部七档推理强度。每个能生成独立供应商控制参数的推理档位都会发起真实请求；没有实际控制参数，或与另一档位使用同一参数的项目会明确显示“跳过”，不会重复计为独立能力。探针范围不依赖当前表单是否已经勾选，因此可以发现尚未配置的能力。探针使用轻量内置素材，真实请求仍可能产生少量 Token 与费用。文本探针失败时会立即停止；其余项目最多四项并行、单项等待不超过 45 秒，页面最长等待四分钟。测试完成后可点击“应用通过项”把成功的多模态能力和推理档位写回当前表单，再由管理员确认保存；若所有实际发起的推理档位均失败，系统不会应用失败结果。
推理探针验证的是服务能否接受该档位的独立控制参数并完成回答，不能证明服务商内部一定使用了不同计算量；最终能力仍应结合服务商文档判断。协议本身不能发送的多模态类型不会列入探针范围，也不会被误判为支持。
推理强度共有“关闭、极低、低、中、高、超高、最高”七档。用户端只显示当前模型已勾选的档位；切换模型后，如果原档位不受新模型支持，系统会自动采用新模型的默认强度。
不同服务商对推理强度的支持并不相同。例如，有些模型只有“关闭 / 开启”，有些模型支持“低 / 中 / 高”，只有少数模型支持“超高”或“最高”。请以服务商当前模型文档为准，不建议为了让选项更多而全部勾选。默认强度必须属于已勾选档位。
原生搜索
“原生搜索”用于 OpenAI Responses 模型。启用后，系统会在调用该模型时加入 OpenAI 内置的 web_search 工具，由模型按需要自行联网检索；对话过程中会展示 OpenAI 原生搜索活动，并在模型返回引用时展示来源信息。
| 配置项 | 说明 | 建议 |
|---|---|---|
| 启用 OpenAI web_search | 是否允许该模型使用 OpenAI 内置搜索 | 只给真实 OpenAI Responses 模型开启 |
| 搜索模式 | 自动判断或强制搜索 | 普通对话建议“自动判断”，必须核验实时信息的模型可选“强制搜索” |
| 工具类型 | web_search 或兼容预览类型 | 新接入优先使用 web_search；旧接口报错时再切到 preview 类型 |
| 上下文量 | 搜索结果占用的上下文预算 | 默认“中”，需要更完整网页信息时再调高 |
| 展示搜索来源 | 请求模型服务返回搜索查询和来源网页 | 建议开启，便于用户确认联网搜索依据 |
启用 OpenAI 原生搜索后，模型会自行完成联网搜索。非 OpenAI Responses 模型、国内兼容接口或自建模型如需联网，请由部署人员接入提供搜索能力的 MCP 服务器。
全局配置
| 配置项 | 说明 | 建议 |
|---|---|---|
| 预设类型 | 关闭、附加或覆盖系统预设 | 普通模型用“关闭”或“附加” |
| 系统预设 | 该模型专属系统提示词 | 不要写过长，避免影响用户任务 |
| 附加参数 | 额外传给模型接口的 JSON | 默认留空；仅在供应商明确要求时填写合法 JSON |
附加参数默认不填，切换供应商模板或内置模型也不会自动填入。model、messages、tools、temperature、stream 等由系统控制的字段不能填写，保存时会提示是哪个字段。只有供应商明确要求额外字段时再填写，例如：
json
{
"max_tokens": 8192
}导入、复制和测试
| 操作 | 说明 |
|---|---|
| 复制 | 复制当前模型配置，适合为同一服务商新增不同模型；API Key 不会被复制，保存前要重新填写 |
| 导入/导出 | 在表单内导入或导出模型配置 JSON；导出不含 API Key，导入也从不修改 API Key（编辑已有模型时沿用已保存的密钥，新建时用表单里填写的）；只应用类型正确的字段 |
| 真实探针 | 经管理员确认后，实际测试文本、协议可发送的全部多模态能力和全部七档推理强度；测试结果可应用到表单 |
| 删除 | 删除不再使用的模型配置 |
列表里的 API Key 只显示脱敏值。测试连接、获取远端模型列表时，已保存的模型可以直接用脱敏值（由服务端换成已保存的密钥）；新建或复制出来的模型要先填写 API Key，否则会提示「请重新填写 API Key」，不会把脱敏值发给服务商。
常见问题
模型显示“启用”但用户端不能用？
先检查 API Key、基础地址、Endpoint Path 和绑定模型是否正确，再用“真实探针”确认接口是否可调用。
计费系数和 Token 计费怎么选？
如果模型每次调用成本差不多，用固定计费系数即可。如果成本主要随 Token 增长，建议开启 Token 计费。
多模态全部勾上可以吗？
不建议。只勾选服务商实际支持的能力，否则用户上传文件后可能调用失败。
推理强度应该怎么选？
普通模型可只保留“关闭”；开关型推理模型可配置“关闭”和一个开启档位；支持分级推理的模型再按服务商文档勾选“极低”到“最高”。不确定时直接运行真实探针，它会逐档测试并允许应用通过项；服务接受请求不等于供应商内部一定使用了不同计算量，仍应结合官方文档判断。
Claude（Anthropic Messages）的推理强度怎么生效？
后台按模型 ID 识别 Claude 的具体型号（网关前缀、Bedrock / Vertex 写法、日期后缀和 -latest 都能识别），再换成该型号接受的参数：
- 新模型（Opus 5.5、Sonnet 5.5、Fable 5.1、Mythos 5.1、Fable 5、Mythos 5、Opus 5、Sonnet 5、Opus 4.8 / 4.7 / 4.6、Sonnet 4.6）按档位发自适应思考与强度。Opus 5.5、Fable、Mythos 不能关闭思考，没有「关闭」档（旧配置里的「关闭」按「低」发送）；Sonnet 5.5 的「关闭」表示只在工具调用之间思考；Sonnet 4.6 没有「超高」。
- 手动思考的模型（Opus 4.5、Sonnet 4.5、Haiku 4.5 及更早的 Claude 4 / 3.7）按思考预算发送：「低」2048、「中」8192、「高」及以上 16384 token（Opus 4.5 另带强度）。从模型目录新选这些模型时默认「关闭」；已经添加的模型保持原来的默认档位，如需默认关闭，在模型设置里把默认强度改成「关闭」。
- Claude 3.5 / 3 不支持思考，推理强度不生效。
- 识别不出的模型（例如网关自定义的别名）不会自动加推理参数，只原样发送附加参数里手写的
thinking/output_config；选「关闭」时去掉thinking和output_config里的强度（effort），output_config的其他字段保留。
其他会随型号自动调整的参数：
- 输出上限：附加参数没写
max_tokens时，新模型开思考默认 16384，手动思考为「预算 + 4096」，其余 4096。这只是上限，按实际输出计费，但可能比以前多用输出 token。附加参数或系统内部设置的上限不会被提高，手动思考的预算会缩到上限以内；连最低预算（1024）都放不下时，这次请求不开思考。 - 采样参数：Claude 4.7 及以后与 5 系列不接受
top_p、top_k（以及非默认温度），会自动去掉并在服务端日志里提示；4.6 及更早只在开思考时受限（去掉top_k，top_p只保留 0.95 – 1）。 - 强制调用工具：Opus 5.5、Sonnet 5.5、Fable 5.1、Mythos 5.1 以及开着手动思考时不支持，会改为由模型自行决定。
“真实探针”按同样的规则报告：型号不支持的档位显示“跳过”；手动思考模型的「超高 / 最高」与「高」参数相同，也显示“跳过”。对识别出的型号，探针会暂时忽略附加参数里手写的 thinking 与强度，逐档如实测试；识别不出的模型照常带上手写参数。
开着思考的 Claude、Gemini 多次调用工具时，思考会带回给模型吗？
会。在一次回复里（同一个模型），服务端把模型上一步的思考块与签名（Claude）、思考签名（Gemini）原样带回下一次请求，这是两家在工具调用中保持推理连续的要求：
- 带回用的签名与回放内容只保存在这次回复的内存里：不写进对话记录，不出现在页面、日志和工具的输入里；思考过程的正文与以前一样会显示，并随轮次记录保存。下一条消息开始的新回复不带以前的思考状态。
- Claude：较早的对话被整理（上下文接近上限时压缩），或附件这次没能读取、使之前的内容变了时，之前的思考块不再带回；手动思考的模型（Opus 4.5、Sonnet 4.5 等）这时在本次回复余下的工具调用里不开思考，下一条消息恢复按档位发送。带着思考块的请求被拒（HTTP 400，例如中转服务改动了请求内容）时，自动去掉全部思考状态重试一次；Sonnet 5.5 的「关闭」档在去掉思考块后仍可能被拒，这时按原错误提示。被拒的请求是否计费取决于模型服务或中转服务，这里不作承诺。
- Gemini：签名按记录原样带回，不做上面的整理判定；记录与历史对不上时，Gemini 3 系列给原本带签名的调用补官方文档给出的占位值，尽量避免请求被拒，但不能保证。思考摘要显示为思考过程，不再混进回复正文。
OpenCode Go 拉取到模型，但对话提示请求无效？
确认“调用协议”是 OpenCode Go Chat Completions，基础地址是 https://opencode.ai/zen/go，Endpoint Path 是 /v1/chat/completions。OpenCode Go 要求编码客户端携带专属客户端标识和稳定会话标识；99Agent 只会在独立 OpenCode Go 协议中自动补齐这两个请求头。
OpenCode Go 虽然使用统一账号与基础地址，但会按模型路由到 Chat Completions、Responses 或 Messages 三类端点。当前模板按 OpenCode 官方端点表，只显示 16 个 Chat Completions 模型；选择其中一个模型时，后台会直接填入由 Pi 注册表、供应商资料与实网验证共同维护的名称、上下文、图片输入和推理档位预设，不需要管理员逐项猜测。远程列表用于确认账号当前可见模型，“真实探针”用于复核预设并发现当前端点额外接受的能力。Grok、GPT 5.6 Luna、Muse、MiniMax 与 Qwen 等使用 Responses / Messages 的模型不能混用当前 Chat 协议，否则会出现“能看到模型但请求无效”。OpenCode Go 协议允许真实探测图片输入，deepseek-v4.1-flash 当前已通过图片探针。修改协议后先用“真实探针”验证，再开启模型。