DEEIX Chat 把模型能力拆成三个互不影响的控制项:模型默认参数、参数透传策略、供应商官方原生工具。这一页给出真实的 JSON 字段、后端过滤顺序,以及上线前怎么逐层验证。

入口位置#

  • 模型默认参数、参数控件和官方工具:管理端 > 模型 > 新增或编辑模型 > 模型能力。
  • 参数透传:管理端 > 会话配置 > 参数透传。
  • 官方工具计费:管理端 > 计费 > 工具定价。

按这个顺序配置。控件只能渲染模型声明的参数,声明过的参数也只有路径被透传策略放行后才能进入上游。

一个参数怎么进入模型#

每次对话都走同一条过滤链,后端按下面的顺序执行:

  1. 读取透传策略。如果是禁止透传,到这里就结束:用户参数和模型默认参数都不会下发。
  2. 以模型的 defaultOptions 为基础,合并用户保存的参数。
  3. 对 lockedOptionPaths 里的每条路径,用 defaultOptions 的值覆盖合并结果。没有默认值的锁定路径会被忽略。
  4. 从合并结果里取出 tools,只保留当前协议下 nativeTools(或旧字段 nativeToolKeys)中启用且匹配的工具。
  5. 执行策略。白名单只复制 default 加当前协议主键里的路径;黑名单保留其余全部字段。
  6. 删除所有系统拦截字段;黑名单模式下再删除 model_option_denied_paths 里的路径。
  7. 校正取值:OpenAI 的 service_tier 只保留 default、flex、priority,图像 partial_images 只保留 0–3,xAI 视频字段会被规范化。
  8. 把过滤后的官方工具重新挂回 tools。

有两点要记住。第一,optionControls 只由对话页用来绘制参数面板,后端不会把它发给模型。第二,模型的 defaultOptions 同样要过策略,所以白名单模式下,默认参数的路径如果没有被放行,也会被丢掉。

模型能力 JSON#

可视化配置会把这些字段写进模型能力 JSON。

字段类型含义
defaultOptionsobject默认请求参数,按路径嵌套。用户没有单独保存参数时使用;仍然要过透传策略。
optionControlsarray参数面板控件,每项为 {path, type, label?, description?, options?}。type 支持 text、select、number、boolean;select 应提供 options。
lockedOptionPathsarray锁定为 defaultOptions 值的路径,用户无法修改。
nativeToolsarray允许的官方原生工具,每项为 {key, protocols, type, label, enabled, defaultEnabled, payload}。
nativeToolKeysarray用工具 Key 引用内置工具的旧写法。后端仍会读取,可视化配置保存时会删除。
promptCacheobjectOpenAI 提示缓存配置:enabled、mode(implicit 或 explicit)、ttl(显式模式为 30m)。仅适用于 OpenAI Chat Completions 和 Responses 路由。
image.streamboolean图像流式调用。false 表示关闭;默认开启。

配置默认参数和参数控件#

模型能力
  1. 打开模型,新增模型或编辑已有模型。
  2. 在模型表单里打开模型能力,点击可视化配置(推荐)。
  3. 进入参数页,为每个参数新增一行。
  4. 参数填真实路径,例如 temperature、reasoning.effort、generationConfig.temperature。
  5. 默认值填 JSON 值。它写入 defaultOptions,同时作为该参数的请求默认值。
  6. 填名称和说明,让对话页的控件可读。
  7. 选择类型。select 需要填写逗号分隔的选项。
  8. 只有值必须固定时才打开锁定。锁定的行必须有默认值;没有默认值的锁定行在保存时会被丢弃。

只想让模型带上默认值、不给用户控件时,填默认值、留空名称即可。只想给控件、不带默认值时,把默认值留空。

需要粘贴完整配置或表单无法表达的结构时,才用高级 JSON。如果模型生成图片,图像流式调用对应 image.stream。

模型能力配置

配置官方工具#

官方原生工具
  1. 打开模型能力 > 官方工具。
  2. 从内置列表选择并开启,或选择自定义官方工具新增。
  3. 填写下面的字段。
字段含义
工具 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_completionsOpenAI Chat Completions。
openai_responsesOpenAI Responses。
openai_image_generationsOpenAI 图像生成。
openai_image_editsOpenAI 图像编辑。
anthropic_messagesAnthropic Messages。
gemini_generate_contentGoogle Generate Content。
google_image_generationGoogle 图像生成。
gemini_interactionsGoogle Interactions。
xai_responsesxAI Responses。
xai_imagexAI 图像生成。
xai_image_editsxAI 图像编辑。
xai_videoxAI 视频生成。
xai_video_extensionsxAI 视频扩展。
openrouter_chat_completionsOpenRouter Chat Completions。
openrouter_responsesOpenRouter Responses。
openrouter_imagesOpenRouter 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。

验证配置#

对话中的模型配置
  1. 在模型里对模型运行测试,确认平台模型和上游来源可用。
  2. 用普通用户身份新建对话并选择该模型。
  3. 打开模型配置,确认参数控件、名称和默认值。
  4. 修改一个已放行参数并发送消息,确认结果变化。
  5. 修改一个锁定参数,确认它仍然保持管理员默认值。
  6. 开启一个官方工具并发送消息,确认模型能实际使用。
  7. 到日志和计费查看模型用量、工具用量和费用记录。

面向团队上线时,先只开放少量低风险路径和一两个工具,日志正常后再逐步扩大。

常见问题#

现象原因处理方式
对话页看不到某个参数模型没有对应的 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
能力 JSONdefaultOptions、optionControls、lockedOptionPaths、nativeTools、nativeToolKeys、promptCache、image.stream

相关页面#