olares-router

router（路由器和模型控制台）

**共享入口：**加载 ../olares-shared/SKILL.md，了解套件路由、活动配置选择、平台入口，以及认证继续／停止关卡。只有在确实需要登录、切换配置、存储令牌或恢复认证时，才加载其中的认证参考资料。

使用 olares-cli router <verb> --help 获取权威语法。

适用场景

• 让 Olares 使用云供应商的模型，或查看已有模型。
• 安装、配置或诊断在此设备上运行的模型应用。
• 决定调用方可以在 model 字段中填写什么：别名、模型组或默认类别。
• 为调用模型的软件发放密钥和配额，并查看其用量。
• 从命令行向模型发送任务：聊天、嵌入、重排序、网络搜索与抓取、翻译、图像、视频、双向语音以及 OCR。

核心概念：每次调用都会经过 Router，这是每个 Olares 唯一的 AI 网关。Router 管理供应商、模型、密钥、配额和用量记录，但本身不运行模型。本地模型运行在模型应用中，其自带的模型控制台会下载权重、启动引擎，并提供 Router 转发请求的 OpenAI 兼容端点。因此，本地模型有两种状态，而非一种：平台显示容器是否运行，应用显示模型能否响应；容器会在权重加载完成前几分钟就报告 running。切勿将其中一种状态当作另一种状态的证据。架构和身份是更完整的说明，建议在首次写入前阅读。

所有动词都要求 Olares 1.12.7+，因为 Router 以 router Market 条目的形式提供，该条目要求此版本。Router 是仅限管理员使用的应用：非管理员配置看不到其入口，因此这里的每个动词都会报告它未安装。在判断是否缺少应用前，请使用 olares-cli profile whoami 检查角色，并使用 olares-cli market list --mine 检查应用。

快速入口

任务	阅读	首条命令
验证模型能否响应	本文件	olares-cli router call chat "hello"
查看此配置可以调用什么	本文件	olares-cli router call models
让 Olares 使用云供应商的模型	配置外部供应商	olares-cli router provider create --type openai --credentials-json @openai.json --validate
查看失败的调用记录了什么	本文件	olares-cli router usage list --limit 5

调用无需密钥：Router 会从平台读取调用方身份，因此 router call 会以活动配置的身份发起。添加供应商需要两次写入，而非一次——provider create 用于保存凭据，model import 才能让模型可供调用，两者缺一不可。

哪一层负责这项更改

意图	所属位置
使用供应商托管的模型	provider create + model import；如果端点会发布自己的列表，则使用 provider sync-models
在此机器上运行模型	对于固定版本的模型，使用 olares-market 的 market install；对于引擎基础镜像，使用 market clone。应用运行后，Router 会创建 provider
更改本地模型提供的服务或启动方式	model spec edit <model> — 模型卡片由应用负责；不属于 Router 条目
更改 Router 路由所用的地址、凭据或启用状态	provider update
修复安装失败的问题	先运行 provider get <app>，然后运行 model progress --app <app> / model retry --app <app>
重启运行异常的引擎	model restart <model>，它会重新启动推理进程，但不会更改模型卡片
停止、恢复模型应用，或将其绑定到 GPU	olares-market 和 olares-settings — 这些不归 Router 负责

source 为 olares 的 provider 属于 Market 应用。其地址和生命周期由 Market 管理；provider delete 会拒绝删除它，需使用 olares-cli market uninstall <app> 卸载。

动词索引

类别	动词	触发时阅读
Router 的位置，以及你的身份	没有专属动词——每个动词都会解析它；无法解析时也会说明原因	架构与身份
云服务商及其模型	provider list/get/types/create/update/delete/validate/credentials/history/rollback/sync-models，在条目尚不存在时使用 provider validate --draft，以及 model get/import/add/update/remove	配置外部服务商
本地 LLM 应用	provider register、model status/progress/retry/restart，以及 olares-market 的 install / clone	本地 LLM 应用
本地嵌入、音频、OCR、CLIP	相同的动词，不同的模式	本地多模态应用
本地模型声明自身的类型	model spec show/edit/file/set、model restart	本地 LLM 应用
已配置的内容	model list、model get	名称、默认值与访问控制
调用方可以传入的名称	route list/get/create/rename/enable/disable/delete/add/remove，通过 route list --kind default 查看 default-* 类别，并使用 route candidates/pin/unpin 指定其中某个名称对应的模型	名称、默认值与访问控制
访问控制	key issue/list/update/revoke/current、quota set/list/clear	名称、默认值与访问控制
发生过什么	usage summary/list/export/retention/apps、audit list/get	用量与审计
每次调用需要什么，以及调用失败的原因	call models、key current、call ocr	调用约定
用文字向模型提问	call chat/responses/count-tokens/embed/rerank/search/scrape	文本与 Web
翻译，包括完整的转录文本	call translate，可配合 --detect、--languages 或 --transcript 使用	翻译
生成或编辑图片，或生成片段、音轨或网格	call image/video/music/3d——编辑图片时使用 --operation edit --image；music 和 3d 需要 --model，而 call music format/draft/alignment/cancel 是 music 专用命令	图片、片段、音轨与网格
双向语音处理	call transcribe/listen/speak/clone/dialogue/vad/diarize/speaker-embed/enhance/align、call task get/result/list/cancel	音频
生命周期超出单次调用的语音，以及已朗读的内容	call voice list/get/add/design/settings/delete、call history list/get/download/delete	语音库与朗读历史
单个应用内部	model status/progress/retry/restart、model diag gpu/config/endpoints，都使用 --app	模型控制台
无法正常工作的调用或模型	上述任意命令	判断问题出在哪一层

命名

• 在可能产生歧义的地方，模型都以 <provider>/<model> 的形式指定，例如 --model、配额和密钥的允许列表。router model list 会同时显示两部分。不带斜杠的名称是路由——别名、分组或 default-* 类别——且必须已存在。
• 每个本地安装的模型应用都是名为 Olares 的提供商，因此本地模型的限定名称并不唯一。<app_name>/<model> 可以指定其中一个，例如 llamacppqwen3v3/qwen3-8b；应用的显示标题也可以，router model list 会在 SERVED BY 中显示该标题。模型 ID 是唯一始终能指定某一行的标识；对于有歧义的引用，系统会拒绝操作并列出候选项，而不是擅自选定一个。
• 提供商可用其标题、Olares 应用名称或 ID 来指定。模型应用通过其 Olares 应用 ID（llamacppqwen3627bggufv3）指定；provider register 和连接到 Model Console 的 model 子命令中的 --app 都需要此 ID。否则，这些子命令会接受模型名称，并询问 Router 是哪个应用在提供该模型；--app 会跳过 Router，因此即使 Router 出问题，这些子命令仍然可用。
• 调用 Router 的应用在此处没有对应条目：Olares 会在边缘端为其背书，调用到达时会携带 appid——即经过哈希处理的应用名称，系统应用则直接使用其名称。因此，此类应用不能注册或撤销；olares-cli market list --mine 可查看它是否在此处，usage --by caller_app 可查看它消耗了多少用量，而 quota set --caller-app 是唯一可用于控制它的手段。

安全与升级处理

• 用户指定的配置请求即授权执行其隐含的整套流程：创建提供商、导入模型并验证它们，无需逐项再次确认。
• 对用户未指定的对象执行 provider delete、key revoke、quota clear 或 route delete 前，请再次询问——这些操作会影响仍依赖该对象的调用方。route disable 可撤销，且会保留路由成员；route delete 则会释放该名称。
• 绝不在文件或 stdin 可行时将凭据放入 Shell 参数；--credentials-json 两种方式都能读取。绝不在将要共享的记录中打印明文 sk- 密钥：key issue 会按设计仅显示一次。
• usage retention --days 会立即删除新时间窗口之外的逐次调用记录，缩短保留期限后无法撤销。每日汇总会保留，因此缩短用户未要求调整的期限前请先确认。
• model spec edit --engine-args 和 model restart 都会重新启动为模型提供服务的进程；在权重再次加载完成前，模型不会响应——大型模型可能需要几分钟。优先使用 model spec edit 而非 model spec set：前者会将更改合并到应用当前提供的配置卡中，并更新 Router 的副本；后者会替换应用中的文档，替换时省略的字段将不复存在。
• 写入操作超时后，未先读取错误信息前绝不重试。 Router 只有三种音乐提交操作带有幂等键，其他操作都没有，因此第二次尝试就是第二个请求：key issue 会再生成一个密钥，provider rollback 会再追加一个版本，router call 会再次计费。错误信息会说明结果未知，以及重试会对该路由造成什么影响——大多数重复操作都会被拒绝，因此重试是安全的；收到 409 证明第一次操作已成功。读取操作失败后通常可以重新执行，包括 task result：再次收集同一结果时，会因任务绑定上的比较并交换失败而只结算一次，因此此处重试消耗的是请求，而非工作量。
• 已配置但不响应的模型属于诊断问题，而非配置变更。编辑任何内容前，请先参阅判断问题出在哪一层。
• 持续出现身份验证失败时，请停止并交由共享身份验证关卡处理；目标提供商、模型、应用或用户存在歧义时，也请停止。