50 lines
6.0 KiB
Markdown
50 lines
6.0 KiB
Markdown
# 香港 CMI LiteLLM 多提供商代理
|
||
|
||
- 公网 OpenAI-compatible 入口为 `https://api.opfo.xyz/v1`，由 Caddy 终止 TLS 后通过外部 Docker 网络 `hk-web` 反向代理到 `litellm-api:1049`。
|
||
- LiteLLM 不使用 host network，也不向宿主机发布端口；容器内监听 `0.0.0.0:1049` 仅供 `hk-web` 上的 Caddy 访问。
|
||
- 默认监听端口为 `1049`；需要修改时必须同时更新 Arcane 的 `LITELLM_PORT` 和 Caddy 的上游端口。
|
||
- 客户端使用 `Authorization: Bearer <LITELLM_MASTER_KEY>`；认证由 LiteLLM 执行，Caddy 仅负责 TLS 和反向代理并保留该请求头。
|
||
- ADC 与 `LITELLM_MASTER_KEY` 仅存放于 Arcane `.env`，不得写入 Git、文档或日志。
|
||
- 对外模型别名包括 `gemini-3.6-flash`、`gemini-3.5-flash-lite`、
|
||
`google/gemini-embedding-2` 和 `google/gemini-3.8-flash`；后两者仍通过
|
||
Vertex AI ADC 路由。
|
||
- 2026-10-25 同步 tools-pve 已验证的 LiteLLM 1.104.2 固定镜像，以及 `models.yaml` 中的提供商映射。`latest` 是维护的别名，不是自动发现所有厂商的新模型。
|
||
- `provider_routes.py` 是同日 tools-pve 的路由生成器快照；更新提供商逻辑时应同步比对两端。HK 的 `render_config.py` 不接入数据库管理或 OAuth，保留现有主密钥认证，个人语音输入走独立的 Vertex 路线。
|
||
- Arcane Project 本地变量增加 `ZENMUX_SUBSCRIPTION_API_KEY`、`ZENMUX_PAYG_API_KEY`、`OPENROUTER_API_KEY`。只有相应凭据存在时才生成该组路由；真实值不进入 Git。
|
||
- Claude 使用 ZenMux 原生 Anthropic Messages 路径，订阅与 `-payg` 显式分开；开源模型使用 ZenMux 订阅优先、同模型 OpenRouter 后备。不自动回退至 ZenMux PAYG。
|
||
- HK 合成请求实测 AI Studio 返回 `User location is not supported for the API use`，因此 Compose 不传入 AI Studio 凭据，也不发布其路线。tools-pve 上原有 AI Studio 功能不受影响。OAuth 会话和会议处理程序没有复制至 HK。
|
||
- Vertex 继续使用 HK 原有 ADC。旧 `gemini-3.6-flash` 别名保留，但指向当前映射的 `gemini-3.8-flash`；其余旧别名保留。
|
||
- 当前实际配置由启动脚本生成至 `/tmp/litellm.yaml`；旧 `config.yaml` 仅作为历史参考，不再挂载。
|
||
- 升级只重建 LiteLLM，不变更 Caddy、HAProxy、其他项目及 ADC 卷。失败时回退本次 Git 提交并同步，再按需要 Redeploy，禁止删除卷。
|
||
|
||
## Spokenly 个人语音输入
|
||
|
||
- 基础地址：`https://api.opfo.xyz/v1`。
|
||
- 转写完整地址：`https://api.opfo.xyz/v1/audio/transcriptions`。
|
||
- 模型：`gemini-transcribe-personal`，真实上游为 `vertex_ai/gemini-3.5-transcribe`，区域 `global`，复用 HK ADC。
|
||
- API Key：HK 现有 LiteLLM 主密钥，不是 tools-pve 客户端 key，也不是 ZenMux key。
|
||
- 响应使用 `json`；不请求时间戳、说话人分离或 `verbose_json`。当前 LiteLLM 请求 `text` 时实测仍返回 JSON 包装，因此不要选 text。额外 prompt 留空；去口语化由 SMART 负责，不靠提示词。
|
||
- 仅显式带 `personal_dictation: true` 的这条路由经 `vertex_dictation.py` 添加 `generationConfig.audioTranscriptionConfig.mode=SMART` 和 `customVocabulary`。其他转写路线、会议录音以及 tools-pve 配置不改。
|
||
- 当前个人词库只有 10 个人名、10 个公司名，与 tools-pve 相同；从 Obsidian People/Companies 卡片取规范名，以正式工作笔记文档频次与 Hindsight 实体 mention_count 交叉筛选。产品、项目、文档标题和错误别名暂不纳入。旧 SQLite 自动抽取的 100 词快照已因过度引导被替代，SMART 保留。
|
||
- `PERSONAL_VOCABULARY_B64` 只存 Arcane Project 环境（Base64 不是加密）；init 将其解码至现有私有凭据卷 `/credentials/personal-vocabulary.json`，umask 077，LiteLLM 只读挂载，不进入 Git。
|
||
- 更新词库时使用 server-management 的 `scripts/export-entity-dictation-vocabulary.py`，先审查纯实体名称与频次，替换 Arcane 中上述变量并重建 init；单改环境变量不会更新已生成文件。保留旧私有词库以便回滚。升级 LiteLLM 前重跑 `scripts/test-vertex-dictation-wire.py`，确认原生 SMART/热词和普通路线隔离。
|
||
- 验收：OpenAI multipart 音频端点接受一秒静音及 Google 公开 Brooklyn Bridge 语音示例，json 均返回 200，公开样本正确输出 `How old is the Brooklyn Bridge?`。测试证明接口和原生参数有效，不代表中文口语及个人名词已进行识别质量对比。
|
||
|
||
## 四款 ZenMux ASR 对比入口
|
||
|
||
同一 Base URL `https://api.opfo.xyz/v1`、HK 现有密钥，Spokenly 选择自定义 OpenAI-compatible transcription，response_format=json，Prompt 留空，额外 AI Processing 关闭。只切换模型名：
|
||
|
||
| 客户端模型名 | ZenMux 实际型号 |
|
||
| --- | --- |
|
||
| `asr-gpt` | `openai/gpt-transcribe` |
|
||
| `asr-qwen` | `qwen/qwen-audio-3.1-asr-flash` |
|
||
| `asr-doubao` | `bytedance/doubao-seed-asr-2.0` |
|
||
| `asr-mimo` | `xiaomi/mimo-v2.5-asr` |
|
||
|
||
- 四条路线只使用 ZenMux 订阅 key，不注入个人热词或 SMART、不加额外 LLM 改写，不自动切模型或 PAYG。供应商自身默认的标点和规范化未强制覆盖。
|
||
- `zenmux_transcription.py` 将 multipart 文件转换成 ZenMux 要求的 JSON/base64，固定上游 `/api/v1/audio/transcriptions`；不新增服务、端口或音频存储。
|
||
- 适配器只识别四个上游型号，校验固定 ZenMux API 地址，其他 OpenAI／Vertex 路线仍用原适配器。原 `gemini-transcribe-personal` 的 SMART 与个人词库不变，会议管线不动。
|
||
- 本轮只验收非流式文件转写和 JSON 输出。不要请求 speaker labels、时间戳或 verbose_json，也不使用提示词来冒充润色能力。
|
||
- ZenMux 没有返回细分 audio/text token 计量，适配器只转发其音频秒数，不编造 token 拆分；费用以 ZenMux 的实际用量记录为准。
|
||
- 每次升级 LiteLLM，重跑 server-management 的 `scripts/test-zenmux-asr-wire.py`（同步／异步、原音频字节、JSON 转换、其他 provider 不变）和现有 Vertex dictation 回归测试。
|