主题
模型管理
用户端能选哪些对话模型，取决于模型管理。这里至少要配置一个可用模型，否则用户无法正常发起对话，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-... |
| 基础地址 | 模型接口的基础地址 | 服务商 API 文档中的 Base URL / Endpoint | https://api.example.com |
| Endpoint Path | 具体请求路径 | 服务商兼容接口文档 | 默认 /v1/chat/completions，大多数 OpenAI 兼容服务可留空 |
基础地址如果没有写 /v1，系统会自动补成 /v1。例如填写 https://api.example.com，实际调用地址会显示为 https://api.example.com/v1。如果服务商要求 /api/v3/chat/completions、/compatible-mode/v1/chat/completions 这类特殊路径，可按服务商文档调整基础地址或 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 |
附加参数默认不填，切换供应商模板或内置模型也不会自动填入。只有供应商明确要求额外字段时再填写，例如：
json
{
"max_tokens": 8192
}导入、复制和测试
| 操作 | 说明 |
|---|---|
| 复制 | 复制当前模型配置，适合为同一服务商新增不同模型 |
| 导入/导出 | 在表单内导入或导出模型配置 JSON |
| 真实探针 | 经管理员确认后，实际测试文本、协议可发送的全部多模态能力和全部七档推理强度；测试结果可应用到表单 |
| 删除 | 删除不再使用的模型配置 |
常见问题
模型显示“启用”但用户端不能用？
先检查 API Key、基础地址、Endpoint Path 和绑定模型是否正确，再用“真实探针”确认接口是否可调用。
计费系数和 Token 计费怎么选？
如果模型每次调用成本差不多，用固定计费系数即可。如果成本主要随 Token 增长，建议开启 Token 计费。
多模态全部勾上可以吗？
不建议。只勾选服务商实际支持的能力，否则用户上传文件后可能调用失败。
推理强度应该怎么选？
普通模型可只保留“关闭”；开关型推理模型可配置“关闭”和一个开启档位；支持分级推理的模型再按服务商文档勾选“极低”到“最高”。不确定时直接运行真实探针，它会逐档测试并允许应用通过项；服务接受请求不等于供应商内部一定使用了不同计算量，仍应结合官方文档判断。
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 当前已通过图片探针。修改协议后先用“真实探针”验证，再开启模型。