模型与供给后端

使用 moi-cli model 与 moi-cli provider-backend 查询可用路由模型与工作区后端声明模型,读取或配置 llm、embedding、parser 三类模型供给后端、端点与路由策略,以及探测上游服务模型列表。执行前请先完成 配置与身份认证;工作区已写入本地配置时可省略命令中的 --workspace-id。

区分路由模型列表与工作区后端模型

model 命令组提供两类作用范围不同的模型查询命令:

# 1. 查询当前工作区可见的路由模型(含工作区后端声明与满足权限条件的系统模型)
moi-cli -auth pat -o model list --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o model list --workspace-id "$WORKSPACE_ID" --query-param type=embedding
moi-cli -auth pat -o model list-embedding-models --workspace-id "$WORKSPACE_ID"

# 2. 仅查询当前工作区可读 LLM 后端声明的模型
moi-cli -auth pat -o model list-workspace-llm-models --workspace-id "$WORKSPACE_ID"

子命令

对应接口路径

返回范围与用途

model list

/models

返回当前工作区可见的路由模型列表(支持 --query-param type=embedding 等筛选参数),合并工作区自建后端与开放的系统路由模型。

model list-embedding-models

/embedding/models

返回当前工作区可用的嵌入路由模型列表。

model list-workspace-llm-models

/workspaces/{workspace_id}/llm/models

仅返回该工作区可读 LLM 后端显式声明的模型名称与后端信息,不包含未在工作区后端声明的系统路由模型;HTTP 契约见 查询可用模型。

模型出现在上述列表中仅代表配置可见,不等同于已完成模型能力校验或上游端点连通性测试。需要在工作区直接发起对话补全验证时,可使用 model workspace-chat-completion 或 model workspace-chat-completion-stream --output(通过 moi-cli schema model workspace-chat-completion 查看请求体结构)。

查看和管理供给后端、端点与路由

provider-backend 通过 --kind 选择后端类别(可选 llm、embedding、parser,默认为 llm)。全部子命令均作用于当前选定工作区(底层 /llm/backends 路径同样受工作区隔离约束):

# 查看工作区后端列表、单个后端详情、端点列表与路由配置
moi-cli -auth pat -o provider-backend list --workspace-id "$WORKSPACE_ID" --kind llm
moi-cli -auth pat -o provider-backend get --workspace-id "$WORKSPACE_ID" --kind llm --id "$BACKEND_ID"
moi-cli -auth pat -o provider-backend list-endpoints --workspace-id "$WORKSPACE_ID" --kind llm --backend-id "$BACKEND_ID"
moi-cli -auth pat -o provider-backend router --workspace-id "$WORKSPACE_ID" --kind llm

为已有后端新增端点或切换端点在线状态:

# 新增上游端点并记录返回的端点 id
moi-cli -auth pat -o provider-backend create-endpoint \
  --workspace-id "$WORKSPACE_ID" \
  --kind llm \
  --backend-id "$BACKEND_ID" \
  --address 'https://llm-upstream.example.com/v1'

# 显式将端点设为 ONLINE 或 OFFLINE
moi-cli -auth pat -o provider-backend set-endpoint-status \
  --workspace-id "$WORKSPACE_ID" \
  --kind llm \
  --backend-id "$BACKEND_ID" \
  --endpoint-id "$ENDPOINT_ID" \
  --status OFFLINE

警告

切换端点状态前请注意可见性与状态值规则:

  • llm 与 parser 的 list-endpoints 和 get 仅返回处于 ONLINE 状态的端点;将端点设为 OFFLINE 前请先保存创建时返回的 ENDPOINT_ID(读取结果为空不代表端点已删除)。embedding 的端点读取同时保留 ONLINE 与 OFFLINE 两种状态。

  • set-endpoint-status 要求传入明确的 ONLINE 或 OFFLINE:省略或传空字符串会在客户端直接拒绝;传入其他无法识别的非空字符串到达服务端后会按 ONLINE 处理(parser 会先去除首尾空白并转为大写)。操作后请回读确认。

配置后端、更新路由与探测上游模型

在与目标部署匹配的 moi-cli 版本中,将上游提供商密钥保存在受权限保护的本地文件(如 chmod 600 provider.key),通过参数化标志或 model 的 JSON 子命令完成创建、更新、探测与路由调整:

# 创建 LLM 后端(全局 -api-key 仅用于 MOI 产品认证,上游密钥通过 --api-key-file 传入)
moi-cli -auth pat -o provider-backend create \
  --workspace-id "$WORKSPACE_ID" \
  --kind llm \
  --name 'openai-compatible-prod' \
  --type OPENAI \
  --address 'https://llm-upstream.example.com/v1' \
  --models 'qwen3.6-plus,deepseek-v3' \
  --api-key-file ./provider.key

# 更新路由策略与健康检查参数
moi-cli -auth pat -o provider-backend update-router \
  --workspace-id "$WORKSPACE_ID" \
  --kind llm \
  --strategy round_robin \
  --health-check-interval 30 \
  --max-retries 2 \
  --session-affinity=false

# 探测上游服务暴露的模型列表(探测仅请求上游模型列表,不会保存或启用后端)
moi-cli -auth pat -o model probe-llm-models \
  --workspace-id "$WORKSPACE_ID" \
  --address 'https://llm-upstream.example.com/v1' \
  --api-key-file ./provider.key

各配置与探测入口的关键选项对照如下:

子命令

主要配置选项

说明

provider-backend create / model setup-llm-backend

--name、--type、--address、--models(逗号分隔)、--api-key-file、--timeout-seconds、--reasoning-control-protocol、--supported-mime-types

创建后端并声明模型清单;--supported-mime-types 用于 parser 后端。

provider-backend update

--id、--name、--models、--api-key-file、--timeout-seconds、--reasoning-control-protocol、--supported-mime-types

按显式传入的标志更新后端配置(传入空文件给 --api-key-file 会发送显式空密钥)。

provider-backend update-router

--kind、--strategy、--health-check-interval、--max-retries、--session-affinity

更新工作区指定类别后端的路由器策略。

provider-backend probe-backend-models、model probe-llm-models、model probe-embedding-models

--address(或 --id)、--api-key-file

请求上游提供商返回可用模型清单;parser 不支持 probe-backend-models。

model *-workspace-llm-backend、model *-workspace-embedding-backend、model update-workspace-*-router

--json / --json-file

直接提交结构化 JSON 请求体(通过 moi-cli schema model <subcommand> 查看字段)。

警告

执行写入或探测前,请先运行 moi-cli provider-backend <subcommand> --help 核对当前二进制实际支持的标志。早期 0.1.0 离线包中的 provider-backend create、update、update-router、probe-backend-models 与 model setup-llm-backend 未开放 --api-key-file、--models、--type 及路由策略标志:在该旧版二进制下执行 provider-backend update 会发送空对象 {} 而不修改配置,执行 provider-backend update-router 发送空对象 {} 会将路由策略、健康检查间隔、重试次数与会话亲和重置为服务端默认值。若当前客户端缺少上述标志,请向部署管理员获取与目标部署匹配的安装包,或改用支持 --json-file 的子命令及产品 HTTP API。

Parser 后端默认值与多密钥池规则

管理 --kind parser 后端或维护多密钥池后端时,注意以下服务端与客户端适配规则:

moi-cli -auth pat -o provider-backend list --workspace-id "$WORKSPACE_ID" --kind parser
moi-cli -auth pat -o provider-backend list-endpoints --workspace-id "$WORKSPACE_ID" --kind parser --backend-id "$BACKEND_ID"
  • 默认类型与超时上限:创建 parser 后端且未显式指定类型和超时时,服务端默认采用 PARSER_MINERU 类型与 3600 秒超时,超时配置上限为 86400 秒。

  • 响应结构客户端适配:parser 的底层 HTTP 列表接口直接返回 data 数组(空时可为 null),CLI 会统一封装为 backends 或 endpoints 集合;delete 与 set-endpoint-status 的 HTTP 成功响应为 data: null,CLI 输出中的 success: true 为客户端适配字段。

  • 多密钥池(api_keys_encrypted)约束:当后端已配置多密钥池时,仅提交单密钥 api_key(如通过 --api-key-file)会被服务端拒绝;当前 --api-key-file 仅适用于单密钥模式,不支持整池替换。通过底层接口提交显式空数组 api_keys_encrypted: [] 表示退回单密钥模式;未同时提供新的非空 api_key 时,服务端保留原单密钥或原密钥池首项(不会清空全部凭据)。

限制和注意事项

  • 全局 -api-key 选项仅用于认证 MOI 产品 API 请求,不会自动填入上游模型提供商的 api_key。

  • 保存后端或路由配置、列出在线端点或探测上游模型清单,均不等同于已完成真实模型推理或文档解析;变更配置后请通过实际业务调用验证端到端可用性。

最后更新于