DEEIX Chat 把模型能力拆成三个互不影响的控制项:模型默认参数、参数透传策略、供应商官方原生工具。这一页给出真实的 JSON 字段、后端过滤顺序,以及上线前怎么逐层验证。
入口位置#
- 模型默认参数、参数控件和官方工具:管理端 > 模型 > 新增或编辑模型 > 模型能力。
- 参数透传:管理端 > 会话配置 > 参数透传。
- 官方工具计费:管理端 > 计费 > 工具定价。
按这个顺序配置。控件只能渲染模型声明的参数,声明过的参数也只有路径被透传策略放行后才能进入上游。
一个参数怎么进入模型#
每次对话都走同一条过滤链,后端按下面的顺序执行:
- 读取透传策略。如果是禁止透传,到这里就结束:用户参数和模型默认参数都不会下发。
- 以模型的
defaultOptions为基础,合并用户保存的参数。 - 对
lockedOptionPaths里的每条路径,用defaultOptions的值覆盖合并结果。没有默认值的锁定路径会被忽略。 - 从合并结果里取出
tools,只保留当前协议下nativeTools(或旧字段nativeToolKeys)中启用且匹配的工具。 - 执行策略。白名单只复制
default加当前协议主键里的路径;黑名单保留其余全部字段。 - 删除所有系统拦截字段;黑名单模式下再删除
model_option_denied_paths里的路径。 - 校正取值:OpenAI 的
service_tier只保留default、flex、priority,图像partial_images只保留 0–3,xAI 视频字段会被规范化。 - 把过滤后的官方工具重新挂回
tools。
有两点要记住。第一,optionControls 只由对话页用来绘制参数面板,后端不会把它发给模型。第二,模型的 defaultOptions 同样要过策略,所以白名单模式下,默认参数的路径如果没有被放行,也会被丢掉。
模型能力 JSON#
可视化配置会把这些字段写进模型能力 JSON。
| 字段 | 类型 | 含义 |
|---|---|---|
defaultOptions | object | 默认请求参数,按路径嵌套。用户没有单独保存参数时使用;仍然要过透传策略。 |
optionControls | array | 参数面板控件,每项为 {path, type, label?, description?, options?}。type 支持 text、select、number、boolean;select 应提供 options。 |
lockedOptionPaths | array | 锁定为 defaultOptions 值的路径,用户无法修改。 |
nativeTools | array | 允许的官方原生工具,每项为 {key, protocols, type, label, enabled, defaultEnabled, payload}。 |
nativeToolKeys | array | 用工具 Key 引用内置工具的旧写法。后端仍会读取,可视化配置保存时会删除。 |
promptCache | object | OpenAI 提示缓存配置:enabled、mode(implicit 或 explicit)、ttl(显式模式为 30m)。仅适用于 OpenAI Chat Completions 和 Responses 路由。 |
image.stream | boolean | 图像流式调用。false 表示关闭;默认开启。 |
配置默认参数和参数控件#
- 打开模型,新增模型或编辑已有模型。
- 在模型表单里打开模型能力,点击可视化配置(推荐)。
- 进入参数页,为每个参数新增一行。
- 参数填真实路径,例如
temperature、reasoning.effort、generationConfig.temperature。 - 默认值填 JSON 值。它写入
defaultOptions,同时作为该参数的请求默认值。 - 填名称和说明,让对话页的控件可读。
- 选择类型。
select需要填写逗号分隔的选项。 - 只有值必须固定时才打开锁定。锁定的行必须有默认值;没有默认值的锁定行在保存时会被丢弃。
只想让模型带上默认值、不给用户控件时,填默认值、留空名称即可。只想给控件、不带默认值时,把默认值留空。
需要粘贴完整配置或表单无法表达的结构时,才用高级 JSON。如果模型生成图片,图像流式调用对应 image.stream。
配置官方工具#
- 打开模型能力 > 官方工具。
- 从内置列表选择并开启,或选择自定义官方工具新增。
- 填写下面的字段。
| 字段 | 含义 |
|---|---|
| 工具 Key | 唯一标识,例如 openai.web_search。 |
| 适用协议 | 这条定义生效的一个或多个协议。 |
| 类型 | 发给上游的工具类型,例如 web_search、code_interpreter。payload 里已有 type 时可省略。 |
| Payload JSON | 供应商工具对象,必须是 JSON 对象。 |
| 默认开启 | 把工具加入模型默认请求参数。 |
| 配置 | 展开编辑该行的 payload。 |
内置目录覆盖:OpenAI 的 web_search、web_search_preview、shell、image_generation、code_interpreter;Anthropic 的 web_search、web_fetch、code_execution、advisor、tool_search;xAI 的 web_search、x_search、code_interpreter;Google 的 google_search、code_execution、url_context。
如果页面提示“当前路由协议未适配”,说明这条定义可能不适用于模型来源协议。强制开启会按管理员配置透传,上线前必须实测。
用户手写 options.tools 时,平台只保留管理员允许的官方工具。允许工具上的参数会透传;未知工具、MCP 或 function 类工具无法通过 JSON 注入。外部工具应放到 MCP,不在这里配置。
配置参数透传#
打开会话配置 > 参数透传。
| 策略 | 行为 | 适用场景 |
|---|---|---|
| 白名单 | 只放行列出的路径,其余丢弃。 | 生产环境默认。 |
| 黑名单 | 除黑名单和系统拦截外全部透传。 | 可信内部用户或调试。 |
| 禁止透传 | 用户参数和模型默认参数都不下发。 | 强成本或合规管控。 |
model_option_allowed_paths 和 model_option_denied_paths 都是 JSON 对象。键是协议,default 对所有协议生效,协议键只为该协议追加路径。路径用点号表示嵌套,例如 thinking.type、provider.order。含空格或空路径段的写法会被忽略。
系统拦截字段在所有模式下始终删除,且不能通过白名单放行:
model、messages、input、instructions、prompt、system、systemInstruction、headers、api_key、apiKey、base_url、baseURL、stream、previous_response_id、prompt_cache_key、prompt_cache_options、prompt_cache_breakpoint、prompt_cache_retention。
保存前看实时预览。它会列出不过滤的路径(命中白名单)和被过滤的路径(命中黑名单或系统拦截)。黑名单模式下,其余字段会显示为“未列入黑名单”并透传。
协议主键#
策略按协议判断。当前主键如下:
| 主键 | 适用协议 |
|---|---|
default | 所有协议。 |
openai_chat_completions | OpenAI Chat Completions。 |
openai_responses | OpenAI Responses。 |
openai_image_generations | OpenAI 图像生成。 |
openai_image_edits | OpenAI 图像编辑。 |
anthropic_messages | Anthropic Messages。 |
gemini_generate_content | Google Generate Content。 |
google_image_generation | Google 图像生成。 |
gemini_interactions | Google Interactions。 |
xai_responses | xAI Responses。 |
xai_image | xAI 图像生成。 |
xai_image_edits | xAI 图像编辑。 |
xai_video | xAI 视频生成。 |
xai_video_extensions | xAI 视频扩展。 |
openrouter_chat_completions | OpenRouter Chat Completions。 |
openrouter_responses | OpenRouter Responses。 |
openrouter_images | OpenRouter Images。 |
只有所有协议都接受的路径才放到 default,否则按协议单独配置。图像路由常见 size、quality、background、input_fidelity、output_format、resolution;聊天路由常见 temperature、top_p、max_tokens、reasoning.effort。
OpenAI 的 service_tier 只接受 default、flex、priority,其他取值会在发送前被省略。
配置官方工具计费#
打开计费 > 工具定价,开启原生工具计费,再为每个工具设置按次价格。
- 价格按次计算。填
0表示该工具不单独计费,但仍然记录用量。 - 只有成功执行的工具调用会计费,失败调用不计费。
- 自用模式只记录用量。
- 免费模型免除原生工具计费,但 MCP 工具计费不豁免。
- 工具调用周围的模型输入输出仍按模型定价计算。
- 上游没有返回工具调用次数时,不会生成单独的工具账单项。
开关和价格保存在 billing.native_tool_billing_enabled 与 billing.native_tool_pricing_json。
验证配置#
- 在模型里对模型运行测试,确认平台模型和上游来源可用。
- 用普通用户身份新建对话并选择该模型。
- 打开模型配置,确认参数控件、名称和默认值。
- 修改一个已放行参数并发送消息,确认结果变化。
- 修改一个锁定参数,确认它仍然保持管理员默认值。
- 开启一个官方工具并发送消息,确认模型能实际使用。
- 到日志和计费查看模型用量、工具用量和费用记录。
面向团队上线时,先只开放少量低风险路径和一两个工具,日志正常后再逐步扩大。
常见问题#
| 现象 | 原因 | 处理方式 |
|---|---|---|
| 对话页看不到某个参数 | 模型没有对应的 optionControls,或模型没有对用户开放。 | 补上控件,并确认模型状态和可用范围。 |
| 参数可见但调整无效 | 路径没有被策略放行。 | 检查白名单或黑名单,用实时预览确认。 |
| 模型默认参数没有下发 | 白名单模式下默认路径没有加入白名单。 | 把该路径加入 model_option_allowed_paths。 |
| 锁定参数仍然会变 | 该路径没有 defaultOptions 值。 | 给锁定路径补上默认值。 |
| 对话页没有官方工具 | 工具未启用、未打开默认开启,或协议不匹配。 | 检查官方工具、适用协议和默认开启。 |
| 工具能用但没有计费 | 计费关闭、价格为 0、模型免费,或上游没有返回调用次数。 | 开启计费并设置价格,再检查用量记录。 |
| 用户手写的工具被忽略 | 不是允许的官方工具,或属于 MCP/function 类。 | 在模型里启用官方工具,或改用 MCP 配置。 |
参考#
| 项目 | 配置键或字段 |
|---|---|
| 透传策略 | chat.model_option_policy_mode(allowlist、denylist、disabled) |
| 白名单 | chat.model_option_allowed_paths |
| 黑名单 | chat.model_option_denied_paths |
| 原生工具计费开关 | billing.native_tool_billing_enabled |
| 原生工具价格 | billing.native_tool_pricing_json |
| 能力 JSON | defaultOptions、optionControls、lockedOptionPaths、nativeTools、nativeToolKeys、promptCache、image.stream |