13 KiB
tools-pve 统一模型代理
部署状态
2026-10-09：已通过 Arcane 上线，LiteLLM 1.104.2 与 PostgreSQL 均 healthy。 UI HTTP 200；应用 virtual key 的 OpenRouter MiMo 请求返回 OK。 ZenMux Sonnet 5.5 原生 Messages 正常；重复请求证实写入与读取 21,502 prompt-cache tokens。Codex/xAI 已独立授权，SDK 原生请求验证 Luna、Sol 6.1 和 Grok 4.7 返回 OK。用户更新后的 PAYG key 原生 Claude 请求 HTTP 200。 Google AI Studio key 模型目录 HTTP 200，使用上游提供的三个 latest 别名。 17 条路线已加载；原客户端 key 权限已更新，Luna/Sol 的 gateway Responses SSE、 Luna 非流式 Chat Completions、Grok/Gemini 三条 Chat 路线和 PAYG Messages 均实测 OK。 本项目对其他模型的自动 latest 维护尚未实现。
- Environment：
ff859844-8393-4f87-8caf-054df735a65d。 - Project：
06052b47-f640-4e23-968d-bfc25a8a6e7a，名称tools-litellm。 - Git Sync：
49148e73-65ca-43a6-a859-efc9cc750b93；Auto Sync 关闭。 - 宿主机项目目录：
/var/lib/docker/volumes/arcane-agent_agent-data/_data/projects/litellm。 - 管理凭据：.145 的
/home/claw/codex-workspace/server-management/.secrets/tools-litellm.env。 - 普通客户端配置：同目录
tools-litellm-client.env；两者均为 0600，不提交 Git。
架构与入口
部署在 192.168.50.49，LiteLLM 与独立 PostgreSQL 17。
- OpenAI 兼容客户端：
http://192.168.50.49:4000/v1。 - Anthropic SDK：
http://192.168.50.49:4000，请求/v1/messages。 - 管理界面：
http://192.168.50.49:4000/ui。 - PostgreSQL 不发布主机端口。
- named volume：
tools-litellm-database、tools-litellm-oauth。
只使用单个代理 worker，降低 OAuth refresh token 竞争的风险。 所有配置从 Git 生成，不允许 UI 中的模型配置成为另一份权威。 未提供 key 或未完成 OAuth 登录的路线不会进入运行配置。 OAuth 判定检查 auth.json 中 access_token，不仅检查文件存在性： Codex 设备授权期间会先写入冷却占位文件，这不代表已经授权。
Provider 与缓存
ZenMux Claude 使用 Anthropic Messages 上游：
https://zenmux.ai/api/anthropic。
LiteLLM 的 anthropic/anthropic/claude-sonnet-5.5 第一个前缀是
LiteLLM provider，第二个前缀是 ZenMux 的模型 ID，不是笔误。
订阅路线为 claude-sonnet-latest、claude-opus-latest、
claude-haiku-latest；PAYG 路线在同名末尾加 -payg。
不自动由订阅切换到 PAYG，也不设置跨模型 fallback。
Claude 客户端优先使用原生 /v1/messages，保留 cache_control、
稳定的 tools/system 前缀以及原样回传的 thinking/signature。
不能保证每次 cache hit；首次创建、最小缓存长度、TTL 和上游路由都会影响结果。
上线验收需重复发送足够长且完全相同的前缀，检查
cache_creation_input_tokens 和 cache_read_input_tokens，不能只看 HTTP 200。
不把 LiteLLM 的响应缓存当作 Anthropic prompt cache。
实测 ZenMux Sonnet 5.5 会拒绝强制 tool_choice.type=tool/any，
错误由上游返回；使用支持的 auto 模式，不在代理中静默改写调用者的要求。
开放模型已改为 ZenMux 订阅优先、OpenRouter 回退；models.yaml 来自实际 provider 目录。
除 Google 自带 latest 映射由其上游维护外，其他 latest 都是本项目手动维护的稳定别名。
Google AI Studio 使用独立 key 与模型表，已实际查询模型目录，
不把 Google OAuth/ADC 当成 AI Studio API key。
Google 三条模型为 gemini-flash-latest、gemini-flash-lite-latest、gemini-pro-latest。
用户新 provider key 的权威位置是 Arcane tools-litellm Project .env；
不要用 .145 首次生成的 tools-litellm.env 整体覆盖它，那份文件可能还含旧 provider 值。
该本机文件主要用于 master key 管理与数据库凭据恢复；提供商配置必须先从 Arcane 实查。
开源模型主备路由（2026-10-12）
| 客户端稳定别名 | 两侧具体模型 |
|---|---|
deepseek-flash-latest |
deepseek/deepseek-v4.1-flash |
deepseek-pro-latest |
deepseek/deepseek-v4-pro |
glm-latest |
z-ai/glm-5.3-prime |
kimi-latest |
moonshotai/kimi-k3 |
mimo-flash-latest |
xiaomi/mimo-v2.6-flash |
这些原有别名先调用 ZenMux /api/v1，失败后由 Router 转向同名末尾加
-openrouter 的备用组；不是随机分流，不切到 PAYG，也不改变 Claude/OAuth。
DeepSeek Pro 原 OpenRouter 日期版 v4-pro-0813 改为双方共有的 v4-pro，
两侧返回模型 ID 已核验一致，但不能仅据 ID 保证供应商权重实现完全相同。
只配置现有五组，不把整个供应商目录自动开放。
缺 ZenMux key 时原别名仍直接走 OpenRouter；缺 OpenRouter key 时不生成悬空
fallback。普通 virtual key 需同时允许主组与备用组，现有 lan-agents key
通过 /key/update 增补五个备用别名，无需更换 key。
部署所用 SDK 的回环 mock 已验证 402、403、429、500 自动回退。 显式部署级异常策略让 429/500 在第一次失败后冷却 60 秒；402/403 仍会在 下一请求尝试主组，不宣称已按订阅窗口熔断。Router 默认最多一次重试， 不是耗尽后无限等待。两家共享订阅额度的跨模型熔断尚未实现。 请求开始前的失败已覆盖；流式输出中途断开不承诺无缝拼接或恰好一次执行工具。
ZenMux 恢复后重新优先使用它。OpenRouter 会产生其账户费用；缓存不跨 供应商共享。上游工具/推理参数兼容性仍按调用者实际用法验收，不能只凭 短文本成功宣称所有 Agent 工作流均兼容。
密钥
真实 .env 权限 0600，不提交 Git；模板见 .env.example。
ZenMux subscription/PAYG 的 key 需要明确确认用途，不能按外观推断。
数据库密码使用无特殊 URL 字符的随机值，避免 DATABASE_URL 编码问题。
LITELLM_MASTER_KEY 以 sk- 开头，salt 独立随机生成。
UI 使用数据库管理员 kai@litellm.local（只是登录标识，不发送邮件），
设置 disable_env_credential_login: true，禁用 UI_PASSWORD 以及 master key 的网页登录。
用户已修改首次临时密码，临时文件已删除。数据库保存密码哈希，
用户的新密码不写入环境变量，也不由 Agent 保存。
master key 仍能管理 API，用于恢复权限，不再充当网页登录密码。
不能直接用这份配置初始化空库后期待默认 admin 登录：必须预先通过
/user/new 建立管理员，再 /user/update 设置临时密码，随后启用限制。
日常客户端应使用管理界面创建的应用专属 virtual key，不共享 master key。
不要开启输出请求全文的 debug 日志。
独立 OAuth 登录
不复制 Codex CLI、Grok CLI 或 Hermes 的 refresh token。 在目标主机项目目录执行：
bash oauth-login.sh codex
打开终端显示的设备验证网址并输入验证码。
xAI 需要本机浏览器回调。先在浏览器所在电脑保持 SSH 隧道：
ssh -N -L 56121:127.0.0.1:56121 tools@192.168.50.49
然后在 tools-pve 的另一个终端运行：
bash oauth-login.sh xai
打开输出的授权 URL；若 56121 被占用，先关闭占用者再重试， 不要把临时改用的端口当作已有隧道可达。 登录 helper 使用 host network 仅供本地 OAuth 回调，生产代理仍使用独立 bridge。
确认账号实际支持的模型 ID 后，在 models.yaml 的 chatgpt/xai 表添加别名。
OAuth 映射为 gpt-luna-latest -> gpt-6-luna、gpt-sol-latest -> gpt-6.1-sol、
grok-latest -> grok-4.7，独立账号目录与 SDK 请求均已验证。
Codex 路线由 chatgpt/ 访问，优先 /v1/responses；
原生 Responses 使用消息列表形式的 input 和 stream=true，按 SSE 读取到 response.completed。
常规 OpenAI SDK 客户端也可用 /v1/chat/completions，Luna 非流式桥接已实测 OK。
实测直接给字符串 input 会被 Codex backend 拒绝；不要把已授权误写成协议完全兼容。
xAI 路线使用 xai/ 与 use_xai_oauth: true，不能设置 XAI API key 覆盖它。
新增 token 后需重启代理，运行时 refresh 会写回同一个持久卷。
部署及验收
正常走 Arcane Git Sync；Manager 已恢复，本项目已通过控制面部署。
如用户明确同意临时直接部署，将本目录放到 tools-pve，准备 .env 后执行：
docker compose config --quiet
docker compose up -d
docker compose ps
恢复 Arcane 后应纳管这套已有卷和项目，避免生成第二套数据库。 上线必须验证健康、带 virtual key 的模型列表、实际请求、stream 和工具调用； OAuth 与 Claude cache hit 分别验收，未通过不能写成可用。
回滚只停止新增项目或回退配置/image pin，不删除 named volume。
定期 pg_dump 并保留独立备份，数据库卷不是备份。
参考：LiteLLM ChatGPT OAuth、 xAI OAuth 官方源码、 ZenMux prompt cache。
Google Agent Platform 与检索模型
2026-10-09 用户确认 Pro 赠金已绑定结算账号后，接入项目
gen-lang-client-0312436655，区域 global。复用此前已授权的用户 ADC，
保存在既有 tools-litellm-oauth 卷的 /tokens/google/adc.json（0600），
不进 Git；容器通过 GOOGLE_APPLICATION_CREDENTIALS 读取并刷新凭据。
Arcane Project .env 设置 VERTEXAI_ENABLED=true、VERTEXAI_PROJECT、
VERTEXAI_LOCATION。默认关闭该路线，避免仅有项目名就自动发起付费调用。
| 对外路由 | 实际模型 | 验收 |
|---|---|---|
gemini-flash-vertex |
gemini-3.8-flash |
原生及普通客户端 Chat 均成功 |
gemini-flash-lite-vertex |
gemini-3.5-flash-lite |
原生及普通客户端 Chat 均成功 |
gemini-pro-vertex |
gemini-3.1-pro-preview |
原生及普通客户端 Chat 均成功 |
gemini-embedding-2-studio |
AI Studio gemini-embedding-2 |
/v1/embeddings 两条输入返回两条 1024 维向量，index 正确 |
前三条不冒充 Google 厂商自动 latest 别名；保持与 AI Studio 既有路由分开。 Google 官方说明 AI Pro 月赠金可用于 Agent Platform，但本次没有从账单 实证某次请求扣的是赠金；兑换状态由用户确认。赠金耗尽后可能继续产生付费， 当前没有基于 Google 实时赠金余额的硬停机制，不设置自动跨 provider fallback。
AI Studio 当前账号目录含 gemini-embedding-001、gemini-embedding-2-preview、
gemini-embedding-2，没有独立 rerank 模型。优先用已经 GA 的 Embedding 2。
原生 Agent Platform gemini-embedding-2:embedContent 已实测返回 1024 维。
但 LiteLLM 1.104.2 的 vertex_ai/gemini-embedding-2 两条输入只返回一条向量，
故没有开放该代理路由供批量检索使用；不要把 API HTTP 200 当成批量验收。
Google rerank 是 Discovery Engine 的独立 Ranking API，不属于 AI Studio
embedding 接口。候选 semantic-ranker-default@latest、semantic-ranker-fast@latest；
005 为较新模型版本，官方页面 latest 指向说明与表格存在矛盾，不能仅凭别名
断言实际模型版本。当前项目两条路线均返回 403：Discovery Engine API 未启用。
尚未启用或纳入 LiteLLM，可到 Google Console 启用 discoveryengine.googleapis.com
后复测中文排序、权限、价格及延迟。当前 LiteLLM 已包含原生 Vertex rerank 适配。
Hindsight 0.10.1 当前生产仍用 unRaid TEI 的 BAAI/bge-m3 embedding 和
Alibaba-NLP/gte-multilingual-reranker-base rerank，Cohere/rrf 是 fallback。
该版本原生 Google embedding provider 会把 Vertex Embedding 2 拆成逐条请求，
并验证输入与输出数量一致，因此后续可优先原生 Google ADC 路线，而非有问题
的 LiteLLM Vertex embedding 路线。不要直接改生产 provider：即使都选 1024 维，
BGE 与 Gemini 的向量空间不同，必须重嵌入并重建索引。rerank 切换不要求重建向量。
embedding 模型禁止使用自动追踪 latest 的别名，否则升级会混用旧向量。
参考：Google Pro 赠金、 Gemini embedding、 Google Ranking API、 Hindsight 配置。