模型与供给后端¶
使用 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"
子命令 |
对应接口路径 |
返回范围与用途 |
|---|---|---|
|
|
返回当前工作区可见的路由模型列表(支持 |
|
|
返回当前工作区可用的嵌入路由模型列表。 |
|
|
仅返回该工作区可读 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
各配置与探测入口的关键选项对照如下:
子命令 |
主要配置选项 |
说明 |
|---|---|---|
|
|
创建后端并声明模型清单; |
|
|
按显式传入的标志更新后端配置(传入空文件给 |
|
|
更新工作区指定类别后端的路由器策略。 |
|
|
请求上游提供商返回可用模型清单; |
|
|
直接提交结构化 JSON 请求体(通过 |
警告
执行写入或探测前,请先运行 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。保存后端或路由配置、列出在线端点或探测上游模型清单,均不等同于已完成真实模型推理或文档解析;变更配置后请通过实际业务调用验证端到端可用性。