12. 进阶(一):LLM Provider 与模型配置

先选接入方式,再选这个入口实际提供的模型。同一家厂商的 API、账户登录、Coding Plan 和聚合平台是不同入口,不一定共用模型 ID、密钥、额度或上下文窗口。

模型清单和可选档位以当前设置页、模型选择器及实际可用情况为准。

本章截图来自原生 App 的中文界面,使用默认浅色主题,保留导航、供应商列表与配置区;点击图片可查看原尺寸。

你要做什么 从哪里开始
不配置第三方 Key,先试用 登录 omicOS,选择内置免费云端模型
使用自己的 API 或 Coding Plan 设置 · LLM 供应商,选择对应入口并保存 Key
使用第三方账户登录 选择对应 OAuth 卡片,完成授权并测试
在多家免费额度之间自动切换 配置自己的 Key,再选择“免费模型 · 自动切换”
接自建服务或私有网关 设置中“添加供应商”,填写端点、API 格式和模型 ID

图形界面的具体入口见第二部分:设置。无界面部署可用本章的环境变量方式。

12.1 Provider 选择优先级

普通聊天请求按以下顺序解析 provider,命中即止:

  1. 聊天请求里显式指定的 provider(当前对话选择的供应商)。
  2. OMICOS_LLM_PROVIDER。
  3. OMICOS_PROVIDER(旧别名)。
  4. 从模型名推断:provider/model 的前缀,或以 deepseek 开头的模型名。
  5. 从可用 Key 推断:DEEPSEEK_API_KEY → MINIMAX_API_KEY → OPENAI_API_KEY。

都没命中时返回 no model provider configured。mock 被禁用,不能拿它代替真实接入。

界面的默认选择不等于底层的自动推断。 工作台可为新选择提供 omicos-cloud;直接调用接口或无界面启动时,应显式指定 provider 和 model。选择 omicos-free 时,Core 会先从已配置的免费池成员中解析实际路由,它不是一个可直接请求的模型端点。

12.2 Model 选择优先级

  1. 聊天请求里显式指定的 model。
  2. OMICOS_LLM_MODEL。
  3. OMICOS_MODEL(旧别名)。
  4. 运行时的默认值。

普通解析的兜底是 DeepSeek 的 deepseek-v4-flash,其余为 gpt-4o-mini;内置云端和免费池另有自己的默认或路由规则。这些兜底不保证适用于每个供应商,建议始终从该入口的当前清单选择模型。

deepseek/deepseek-v4-flash 中与所选 provider 匹配的路由前缀可以被剥离。但聚合平台的 openai/...、deepseek/... 和 NVIDIA 的命名空间可能就是完整模型 ID 的一部分,不要自行删除斜杠前的内容。

模型在某个入口已被标记为退役时,当前界面会隐藏或阻止选择,Core 也会拒绝相关请求;其他入口的同名模型有独立生命周期。旧对话仍可查看;继续发送前,改选同一入口里仍可用的模型。目录要求更高版本 Core 时,先更新拥有该对话的 Core,而不只是网页界面。

12.3 支持哪些 provider

接入方式 示例 配置要点
内置免费云端 omicos-cloud 需要 omicOS 登录,不需要第三方 API Key
免费额度自动切换池 omicos-free 只在你启用、配置好的成员间路由,不包含内置云端
API / Coding Plan DeepSeek、Qwen、OpenAI、Moonshot/Kimi、MiniMax、各 Coding Plan 等 选对入口和区域,用这个入口签发的 Key
Anthropic anthropic Anthropic Messages 协议,可用对应 Key 或已连接的 OAuth
第三方账户 OAuth Codex、Antigravity、Anthropic、xAI Grok 在对应卡片完成授权,模型与额度由该入口决定
自定义供应商 设置中“添加供应商” 明确端点、API 格式、完整模型 ID 与上下文窗口

Google:Antigravity 与企业 Gemini CLI

个人 Google 账户在当前设置页使用 Antigravity OAuth。企业 Gemini CLI / Cloud Code Assist 的已有凭据仍有独立的导入与刷新路径;状态中会显示 Gemini CLI (enterprise),不要把它与个人账户的登录流程混为一谈。

  1. 在设置中打开 Antigravity OAuth 卡片,点击登录。
  2. 在浏览器完成授权;若界面要求粘贴授权码,按提示把回调页的授权码填回 omicOS。授权码属于凭据,不要发到聊天、截图或反馈里。
  3. 检查 Token、Project 和 Runtime。Missing project / Project required 表示运行条件还没就绪,不能仅凭 Token 存在判断可用。
  4. 点击测试,再在实际对话中发送一句短消息。

本机已有兼容的 CLI 凭据时,也可使用卡片提供的导入入口。为兼容旧选择,内部 provider ID 仍是 gemini-cli;在旧配置或 API 返回中看到它,不代表仍在使用个人 Gemini CLI 登录,也不需要手工改名。

OAuth 显示“已连接”只证明授权状态。具体模型仍可能受账号权限、额度、区域或网络限制;成功登录不保证每个模型都能请求。API 入口与 OAuth 入口的模型 ID 也不应互相照搬。

两种“免费”入口

  • 内置免费云端:使用 omicOS 登录和共享上游额度。每日额度按 UTC 重置,高峰可能限流或暂时不可用。遇到“免费云端模型当前不可用”,可稍后再试,或切换到已配置的自有 API / OAuth。
  • 免费模型 · 自动切换:使用你自己的厂商账户和 Key。先保存 Key,再勾选“加入自动切换”,检查池中的就绪状态,然后在对话选择自动切换入口。
  • 某供应商同时出现在普通分组和“免费模型”分组时,共用同一供应商和 Key,后者只是免费模型筛选视图;国内 / 海外区域入口则可能使用不同账号和 Key。

自动切换只在首个 token 之前、遇到明确的额度耗尽错误时尝试下一家已启用成员。它不会把任意网络失败或生成到一半的回复交给别家继续,也不会替明确选定的供应商自动换厂商。

App 设置:免费模型自动切换池的候选、勾选状态与就绪提示

在“自动切换池统一管理”里核对成员是否勾选、是否就绪;“需要 Key”表示该成员尚缺凭据。图中的模型、数量和当前路由仅展示这台客户端的状态,不是固定配置或免费额度承诺。本图为旧版本示意:Hugging Face 当前不再属于免费自动切换池,免费账户没有月度赠送额度,须购买额度或使用含额度的订阅(见官方定价)。

12.4 API key 从哪来

在 App 的 设置 · LLM 供应商 中选择 API 入口,填写 Key、选择模型,再保存和测试:

App 设置:OpenAI API Key、模型和保存 / 测试入口

图中的 sk-proj-... 是输入框占位符,没有填写真实 Key;按钮能否使用取决于当前配置。截图里的模型只是界面示例,不表示已测试通过。

普通目录供应商与旧 custom_* 模板的 API Key 按以下顺序解析:

  1. 已保存的 auth.json 值:依次检查 $OMICOS_LOCAL_HOME/auth.json、$OMICOS_RUNTIME_HOME/auth.json、~/.omicos/auth.json、旧工作区 <当前目录>/.omicos/auth.json;取第一个包含所需非空字段的文件。
  2. 对应的环境变量。目录可指定 Key 的变量名;没有特别指定时,通常是 provider ID 转大写并将连字符改为下划线,如 ALIBABA_CODING_PLAN_API_KEY。

当前已保存的设置优先于进程继承的旧环境变量。 有保存值时,再 export 同名 Key 不会覆盖它;应在设置里更新该值,或明确清除旧值后再使用环境变量。OAuth 凭据和内置云端的登录令牌不走这条普通 Key 解析链。

内置 anthropic 是一个例外:优先用已连接的 Anthropic OAuth;未连接时,先读 ANTHROPIC_API_KEY 环境变量,再查已保存的 Key。排查时不要把这个入口与 custom_anthropic 的优先级混用。

Ollama 未配置 Key 时会使用本地占位符 ollama。自定义供应商管理器的 Key 使用独立存储字段,不要把显示名称直接拼成环境变量名。Key 是敏感信息,不要提交 auth.json 或把诊断变成打印密钥。

无界面示例(该 provider 没有已保存的 Key 时):

export DEEPSEEK_API_KEY=sk-your-key
export OMICOS_LLM_PROVIDER=deepseek
export OMICOS_LLM_MODEL=deepseek-v4-flash
omicos serve --no-browser

让服务保持运行,再连接工作台或另开终端使用 CLI 发送短消息。监听端口成功不等于 Key 和模型已经验证;真实请求的错误会显示在对话里。

12.5 自定义端点

普通目录供应商的端点优先取 <PROVIDER>_API_BASE,否则取云端目录里的 api_base。没有有效端点时会报错,不会随意回退到另一家厂商。

新配置建议使用设置里的 “添加供应商”:填写名称、端点、Key 和模型,选择与服务器一致的 API 格式。

API 格式 用于哪种接口
OpenAI · Chat Completions /chat/completions
OpenAI · Responses /responses
Anthropic · Messages /messages

App 添加供应商:三种可选 API 格式

截图展开了已有自定义供应商的 API 格式 下拉框,个人配置字段已遮蔽。协议选项来自实际界面,不表示已测试通过;先确认服务支持的协议,再填写自己的配置,不要只凭“OpenAI 兼容”选择格式。

端点填写该服务的 API 根地址(如 https://api.example.com/v1),不要把完整的 /chat/completions、/responses 或 /messages 请求路径再填一遍。“OpenAI 兼容”并不保证同时支持 Chat Completions 与 Responses。 保存后先测试,再在使用这个配置的对话里验证一次。

旧模板 custom_openai / custom_anthropic 仍兼容,但与“添加供应商”不是同一套 ID:

  • custom_openai 使用 Chat Completions;CUSTOM_OPENAI_API_BASE 默认 http://127.0.0.1:8000/v1,Key 可回退到 OPENAI_API_KEY。
  • custom_anthropic 使用 Messages;必须配置 CUSTOM_ANTHROPIC_API_BASE,Key 可回退到 ANTHROPIC_API_KEY。
  • 这两套模板的端点和 Key 都按 已保存值 → 环境变量 查找。需要 Responses 的自建网关,应使用可明确选择 API 格式的自定义供应商管理器。

例如接本地 Chat Completions 服务;模型 ID 换成服务实际提供的值:

export OMICOS_LLM_PROVIDER=custom_openai
export CUSTOM_OPENAI_API_BASE=http://127.0.0.1:8000/v1
export CUSTOM_OPENAI_API_KEY=dummy  # 仅限不校验 Key 的本地服务
export OMICOS_LLM_MODEL=your-served-model-id
omicos serve --no-browser

12.6 云端模型目录

内置目录经 Core 的 /api/models 提供给设置页和选择器,本地缓存默认在 ~/.omicos/cloud-models/models.json。不同入口的同名模型应分别核对能力,不要把一家报告的上下文窗口直接套给另一家。

变量 作用
OMICOS_MODELS_OFFLINE=1 关闭目录云同步,只用本地缓存
OMICOS_MODELS_CLOUD_URL 覆盖目录拉取地址
OMICOS_MODELS_CACHE_DIR 覆盖缓存目录

支持在线模型列表的供应商可在设置中“拉取全部模型”,这只发现列表,结果仍受当前凭据、入口和可用性筛选影响;“拉取并验证可用模型”会逐模型执行简短对话请求,可能消耗该入口额度,免费池“刷新”也会更新已启用且已配置成员的验证结果。目录可见、测试通过、正常对话能用是三个不同检查;验证通过仅说明当前账户此刻可完成基础对话,不保证完整工具或视觉能力,也不保证永久免费。

查看正在连接的本地 Core 返回的 provider ID,不读取密钥(端口换成实际值):

curl -fsS http://127.0.0.1:5055/api/models \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print("\n".join(p["id"] for p in d.get("providers", [])))'

不依赖固定 provider 数量或列表顺序。离线缓存可能过时;刷新目录后仍缺新功能时,检查拥有该对话的 Core 版本。

12.7 视觉模型

设置 · 视觉模型可以跟随主模型,也可以单独选择支持图像输入的模型。内置 API 选项按视觉能力和生命周期筛选;OAuth 与自定义入口仍需通过图片测试确认实际支持,不能仅凭出现在列表里判断。主模型擅长推理,不代表能接收图片;不支持图像的模型也不会因为勾选“让模型看图”就获得视觉能力。

无界面部署可用 OMICOS_VISION_MODEL、OMICOS_VISION_BASE_URL、OMICOS_VISION_API_KEY 指定视觉配置,见环境变量参考。验证视觉路径时,使用一张不含隐私的小图;纯文本请求成功不等于读图路径成功。

12.8 推理档位与上下文窗口

模型选择器根据当前 provider + model 的能力配置展示推理档位。可能是开/关,也可能是多个强度等级;标明始终思考的模型不提供关闭选项,没有可调能力配置的模型不显示相应控件。自定义模型的自动识别只是候选提示,仍要核对服务端协议并测试。不要把另一模型的 low / high / none 原样搬过来。

处理速度档位与推理强度是两件事。只有提供速度控件的模型才可选;“快速”会传递相应服务档位,是否可用和如何计费由供应商决定。

自定义模型的上下文窗口用于预算估算,不会改变服务端真实上限。填写该入口实际支持的 token 数;目录建议需要确认并保存。发送后可从对话的上下文明细核对有效预算,接近上限时再压缩,见与智能体对话。

12.9 远程连接时,配置在哪台机器

先确认对话的运行位置和设置 · 连接中的云端流量路径:

  • 远端直连:模型请求由远端执行,选择器会按远端配置过滤供应商;本机保存的 Key 不会自然出现在远端。
  • 经本地转发(via-local):模型请求借用本机的凭据和网络,远端负责分析计算。适合没有外网的计算节点;远端不持有本机 OAuth 凭据是正常状态。

不要为了让模型出现就复制整套密钥文件到服务器。需要远端独立访问时,明确配置该远端或使用产品提供的显式凭据同步。具体连接流程见远程 / SSH / HPC。

12.10 配好后怎么确认

  1. 保存配置,确认当前入口、区域、完整模型 ID 和 API 格式。
  2. 测试接入。OAuth 还要确认运行状态就绪,不只看已连接。
  3. 在目标对话中发送短消息,确认实际运行位置下能正常回复;需要工具或视觉时,再分别验证相应路径。
现象 先检查什么
没有可选模型 Key / OAuth 是否配置、是否被隐藏、当前运行位置是否改为远端、Core 是否满足目录要求
登录成功但请求被拒绝 账号对该入口和模型的权限、区域、额度;网络诊断应看发请求的机器
测试成功但聊天失败 当前对话的 provider / model、API 格式、网关模型命名空间、工具能力
missing api key 或改了环境变量仍用旧值 检查该入口的已保存设置及凭据归属,不打印 Key
旧模型不可选或被拒绝 更新目录,改选仍可用的模型;不要绕过生命周期限制
免费云端不可用 / 额度耗尽 区分限流、临时不可用与额度耗尽,查看界面提示,或切换已配置的自有接入

反馈问题时提供 provider ID、model ID、Core 版本、运行位置和完整错误文本;授权码、Token、Key、认证头和含凭据的 URL 必须移除。

results matching ""

    No results matching ""