接入与管理模型

业务接入默认通过后台 SDK 声明与发布，见 业务后台 SDK。以下管理流程用于查看、调试及显式治理；代码声明的资源显示来源，不能从管理页无痕修改。

启澜通过“供应商 → 模型 → 应用绑定 → 模型配置 → 智能体”连接模型。每一步都引用精确版本，使发布和回滚可控。

1. 声明模型连接

先在部署环境允许模型 origin，并把密钥名称绑定到同一 origin，见环境变量。在后台 RegistrationManifest 中用 ModelDeclarations.openAIProvider 声明连接，完整代码见后台教程。下面 JSON 是对应 definition 的字段参考：

{
  "mode": "OPENAI_CHAT",
  "endpoint": "https://model.example.com/v1/chat/completions",
  "secretRef": "MODEL_API_KEY",
  "stream": true
}

SDK 创建能力定义并受控发布，不需要手工包装 HTTP 请求。手工管理资源时，控制台或底层 API 使用同一字段结构。

OPENAI_CHAT 要求服务兼容 Chat Completions 请求、工具调用和所需流式格式。stream:true 开启原生文本流；默认 false。仅提供 Responses API 的服务不能直接使用此模式。

REMOTE 用于自己的模型适配服务，支持单次 message/usage 响应和版本化 SSE。Java/Kotlin SPI、注册、续租、流式事件和取消见远程模型提供器与流式接入。

2. 注册模型

{
  "provider": {"id":"primary-provider","version":"1.0.0"},
  "modelId": "your-provider-model-id",
  "capabilities":{"toolCalling":true,"streaming":true}
}

modelId 必须是供应商支持的真实标识。可选 pricing 形如 { "currency":"USD", "inputPerMillion":1, "outputPerMillion":2 }，价格由你维护；示例数字不代表任何供应商报价。

3. 授权到应用

后台使用 ModelDeclarations.binding 声明应用私有绑定；平台管理员也可以授权使用公共模型。例如 definition：

{"model":{"id":"primary-model","version":"1.0.0"}}

多个应用共用模型时，平台管理员在“公共供应商”“公共模型”维护全局资源，并在各应用建立带 "scope":"global" 的绑定。应用管理员不能自行取得公共模型授权。

4. 建立模型配置

{"binding":{"id":"default-binding","version":"1.0.0"},"maxOutputTokens":1024}

最大输出为 1–32768。按短问答、长文本等场景建立不同配置，再让智能体引用相应配置。生成参数放在 parameters，候选策略放在 routing；详见下文。

更新模型与密钥

模型策略变化创建新版本，逐层更新引用，最后切换默认智能体。更新密钥在部署环境完成并重启，通常无需把真实密钥写入新版本。原有在途请求的业务结果按运行与调用记录核查。

费用如何显示

只有完整用量和对应价目都存在时，任务返回配置费用；否则为 null。多币种分开累加，不自动换算。供应商缓存、阶梯折扣、税费和结算差异不在这一统计口径内。

能力声明与检查

在模型目录填写供应商标识、精确供应商版本及 capabilities。根据所选供应商、模型、参数与部署地域填写，不要照抄示例能力。true 是维护者声明支持，false 明确不支持，省略为未知；平台不把手工配置显示成探测通过。

{
  "provider":{"id":"primary-provider","version":"1.0.0"},
  "modelId":"your-provider-model-id",
  "capabilities":{
    "toolCalling":true,
    "structuredOutput":true,
    "streaming":true,
    "contextWindow":32768,
    "maxOutputTokens":4096,
    "regions":["cn"]
  }
}

字段	类型与约束	用途
toolCalling	可选 boolean	Tool、子 Agent 和 UI 函数均要求 true
structuredOutput	可选 boolean	Profile.outputSchema 要求 true
streaming	可选 boolean	Provider.stream=true 要求 true；REMOTE 仍不启用原生流
vision、audio	可选 boolean	记录供应商声明；当前聊天接口输入仍为文本
contextWindow、maxOutputTokens	可选整数 1–10000000	输出上限不能超过窗口；Profile 的保留量不能超过任一已声明限制
regions	可选 1–32 个不重复字符串	全部可能服务地域；小写字母开头，允许字母、数字、连字符，最长 64

Agent 可增加 requiredCapabilities（上述五种布尔能力，不重复）和 allowedModelRegions。存在地域限制时，模型必须声明地域，且全部地域都在允许列表内；这不是供应商物理位置认证。

检查与发布

Agent 列表点击「模型兼容性」，查看精确版本模型、能力状态、配置输出、窗口和地域。需要 APP_ADMIN 或平台管理员。只读 HTTP：

POST /v1/apps/{app}/model-compatibility
Authorization: Bearer <管理凭据>
Content-Type: application/json

{"id":"monitor-agent","version":"1.0.0"}

返回 valid、evidence=DECLARED、checks、errors、warnings 和 contextEstimator=UTF8_BYTES_ESTIMATE。配置不兼容仍返回 200/valid=false；缺失、撤销的外部依赖和鉴权错误按 HTTP 错误返回。草稿 Agent 的外部依赖需已发布，整条草稿链用批次预检。报告不调用模型，也不证明供应商健康。单独发布、批次发布、默认入口和每次固定执行计划使用相同强制规则。

结构化输出

Profile 定义示例：

{
  "binding":{"id":"default-binding","version":"1.0.0"},
  "maxOutputTokens":1024,
  "outputSchema":{
    "type":"object",
    "properties":{"answer":{"type":"string"}},
    "required":["answer"],
    "additionalProperties":false
  }
}

使用平台闭合 JSON Schema 方言；根是 object，所有嵌套对象的属性均在 required 中。OPENAI_CHAT 和 REMOTE 请求添加 response_format，形如 {type:"json_schema",json_schema:{name:"sparktide_output",strict:true,schema:...}}。REMOTE 返回的 message.content 是 JSON 文本，不能改为对象。供应商不兼容参数时返回上游错误，声明不会让不支持的服务自动支持。

最终助手内容严格解析为单个 JSON 对象并校验。原生流先缓存完整结果，验证通过后发送 text.delta；不符合 Schema、附加内容、缺少字段或无效 JSON 时 INVALID_MODEL_OUTPUT，未验证内容不进入文字事件或成功会话。普通文本输出继续按原生增量显示。

上下文与错误处理

每次模型步骤使用消息、工具和格式的 UTF-8 序列化字节数加输出保留量估算上下文。超过已声明窗口时 MODEL_CONTEXT_EXCEEDED，跳过该候选；全部候选不足时终结 Run；这不是实际 Tokenizer，可能保守拒绝，不代表厂商计费或精确容量保障。未声明窗口和输出限制产生 MODEL_LIMIT_UNKNOWN 警告；根任务总预算仍独立生效。成功和失败均按 Run/事件核查，运行中的错误不是聊天受理 HTTP 返回值。

错误	处理
MODEL_CAPABILITY_UNKNOWN	按供应商资料补充新模型版本，不能假定支持
MODEL_CAPABILITY_UNSUPPORTED	更换支持必要能力的模型，或调整 Agent 的业务能力
MODEL_OUTPUT_LIMIT_EXCEEDED	降低输出配置或更换模型
MODEL_REGION_UNKNOWN、MODEL_REGION_DENIED	补充可信声明或调整允许地域
MODEL_CONTEXT_EXCEEDED	减少上下文、知识和工具定义，或选择更大的窗口
INVALID_MODEL_OUTPUT	核查供应商参数与结果，保留 traceId；不展示未验证文本

旧版本升级与回滚

纯文本旧模型仍可用；工具型 Agent 或流式模型缺少必要声明会拒绝新运行。已发布定义不能修改，创建新的 Model→Binding→Profile→Agent，用批次预检和发布切换入口。不要直接替换运行中版本或猜测厂商能力。回滚到旧平台前先切回它能识别的旧配置链；数据库无新增迁移，发布历史保留，工具不自动重放。

配置与使用

先发布供应商、模型及应用绑定。在「模型配置」选择主绑定，候选绑定按每行 id@version 填写，最多 7 个备选；全部版本固定且不得重复。发布 Profile 后由 Agent 引用，再运行兼容性检查；全部候选必须支持该 Agent 的工具、输出格式与地域要求。新运行需要全部依赖已发布且未撤销。

{
  "binding":{"id":"primary","version":"1.0.0"},
  "fallbackBindings":[{"id":"backup","version":"1.0.0"}],
  "maxOutputTokens":1024,
  "routing":{"strategy":"ORDERED","maxAttempts":2,"attemptTimeoutSeconds":10,
    "fallbackOn":["MODEL_UNAVAILABLE","MODEL_TIMED_OUT","MODEL_RATE_LIMITED"]},
  "parameters":{"temperature":0.2,"topP":0.8,"seed":42}
}

配置	默认与约束
strategy	ORDERED 按主绑定和候选顺序；LOWEST_COST 按每次生成的输入字节估算与保留输出量排序，同价保留配置顺序
maxAttempts	默认候选数，1–8 且不超过候选数；每个候选最多一次
attemptTimeoutSeconds	默认 60，1–60 秒；同时受整个任务剩余时限限制
fallbackOn	省略允许三种瞬时错误；[] 关闭错误切换，不关闭上下文容量筛选
temperature	可选有限数值 0–2；传递给供应商 temperature
topP	可选有限数值，大于 0 且不超过 1；传递 top_p
seed	可选整数 0–2147483647；供应商不支持时不会悄悄移除

LOWEST_COST 要求每个候选有完整 pricing，且币种一致；不能自动换算币种。排序是估算，展示费用是配置价目乘供应商返回用量，两者都不是实际结算账单。失败尝试未返回用量时整个任务费用保持未知，不计为零。

运行边界

情况	行为
HTTP 429	MODEL_RATE_LIMITED，可按策略切换
HTTP 408/504 或单次超时	MODEL_TIMED_OUT，可按策略切换
网络失败、HTTP 5xx、选中候选租约失效	MODEL_UNAVAILABLE，可按策略切换
HTTP 401/403	MODEL_AUTH_FAILED，终结当前任务，不切换
其他拒绝请求或无效模型 JSON/消息格式	MODEL_REQUEST_REJECTED / MODEL_PROTOCOL_ERROR，不切换
文字或工具参数已开始返回	即使随后超时，也禁止切换，防止混合答案与重复操作
候选窗口不足	请求发送前标记 SKIPPED，继续已配置候选；全部不足时 MODEL_CONTEXT_EXCEEDED
已执行工具后下一次模型调用故障	保留工具结果，仅切换本次模型生成，工具不重放

每次实际模型尝试消耗根任务步骤与输入预算。maxSteps、maxBudgetUnits 和当前调用/祖先截止时间优先于候选次数；不会为了耗尽候选突破预算。普通文本原生流保留增量；结构化内容先缓存校验，再发送文字，但供应商已开始输出同样禁止故障切换。

观察事件与升级

model.started 带 invocationId、stepId、attempt、binding、model（含 scope）、selectionReason 与 Agent 调用关系。model.completed 再带 status=RESPONDED/FAILED/SKIPPED、errorCode、outputStarted、usage、cost。SKIPPED 不发送 started。RESPONDED 表示收到模型响应，后续 Schema 或工具权限校验仍可能失败；最终结果看 message.completed。

每个模型步骤使用独立 stepId，各次候选拥有不同 invocationId。事件中不包含服务密钥、请求全文或内部提示词。管理聊天页面展示尝试与结果；前端 SDK 保留这些事件，不把一次模型失败当成整个聊天失败，不重新发送聊天请求。

本配置不声明健康探测、熔断、跨模型多模态协议或独立调用账本已完成。升级创建新的 Profile→Agent，批次预检后切换入口。回滚先切换到仅包含旧平台支持字段的旧配置链，再回滚服务；无需数据库迁移，不修改已发布版本。

独立调用账本与费用核对

运行记录中查询每次固定模型尝试、发送边界、用量及价目版本。失败不表示免费；未返回用量保留未知，已有流式回执即使随后超时仍保存。管理员可按供应商原始证据核对，不重新调用模型或工具。完整字段、API、SDK 和升级说明见模型调用账本与核对。

验证供应商健康与协议能力

在模型绑定版本打开「模型健康」执行合成检查，并查看故障隔离与恢复记录。租约不等于模型健康，探测可能计费、不会执行业务工具；说明见模型健康探测与恢复。

应用配额与费用预算

在控制台“配额与预算”配置应用、租户、用户和模型的周期上限，查看预留并核对供应商最终用量。详见配额与费用预算。