学习笔记 · Obsidian
模型网关、自托管与兼容层
结论
网关、路由器和 OpenAI-compatible endpoint 能降低切换成本，但不会自动统一语义。生产抽象应固定“应用最小能力集”，同时保留 provider-specific metadata；否则路由切换后容易出现工具 schema、reasoning、引用、usage 和多模态的静默降级。
集成地图
| 集成 | 包/入口 | 用途 | 生产边界 |
|---|---|---|---|
| any-llm | langchain-anyllm; ChatAnyLLM | 以同一类访问多个 provider | 仍需注入各 provider 凭据；参数和错误语义并非真正同构 |
| Hugging Face | langchain-huggingface; ChatHuggingFace、HuggingFaceEndpoint/Pipeline、Embeddings | Hub endpoint、本地 Transformers pipeline、TEI embeddings | 本地方案需锁定 model revision、tokenizer、量化、device 与显存；endpoint 方案需管理 token/自动扩容 |
| LiteLLM | langchain-litellm; ChatLiteLLM/Router、Embeddings/Router、OCRLoader | 多 provider 统一客户端、路由、fallback | 可同时扩大凭据面和数据路由；必须锁定 model list、fallback 顺序、最大重试和成本上限 |
| LocalAI | langchain-localai | 本地 embeddings 与 reranker | provider 页没有给出 Chat 契约；不应从 LocalAI 本身的 API 能力推导 LangChain 类能力 |
| Ollama | langchain-ollama | 本地 Chat、LLM、Embeddings | 需预拉模型并锁定 tag/digest；生产需设定并发、内存/GPU 上限、keep-alive 与网络隔离 |
| Portkey | portkey_ai + ChatOpenAI gateway | 150+ 模型、虚拟密钥、负载均衡、fallback/retry、trace | provider 页与 logging/tracing 子页是同一网关的两个视角；必须禁止 trace 采集密钥与未授权正文 |
| Ray Serve | ray[serve] | 把 chain/LLM 封装成自定义服务 | 文档是通用骨架；生产还需副本数、并发、backpressure、健康检查、滚动发布和冷启动设计 |
| Shale Protocol | ChatOpenAI + 自定义 base URL | OpenAI drop-in endpoint | 页面只展示简单替代，未证明 tools/schema/usage 兼容；只能在契约测试后使用 |
| TrueFoundry | langchain-openai + gateway base URL | 统一模型网关、LangGraph、观测与治理 | 自定义 gateway 与 OpenAI 官方行为必须分别测试；记录的 prompt/response 需租户隔离与脱敏 |
| Modal | ModalSandbox | GPU serverless container，Deep Agents sandbox backend | provider 页只是导航，认证、超时和 sandbox 边界需以 Modal/子集成文档为准 |
| Daytona | DaytonaSandbox、DataAnalysisTool | 快速启动的多语言 sandbox | provider 页不提供完整认证/隔离契约；sandbox 不能默认获得主应用凭据和网络权限 |
兼容层验收
- 对每个路由目标运行同一套 golden tests：消息角色、stop reason、stream chunk 合并、tool arguments、strict schema、usage、拒答和非 ASCII 文本。
- 错误映射不只看 HTTP status；需保留 provider code/request ID/retry-after，并区分内层 provider 失败与外层 gateway 失败。
- 将 route/provider/model 三者一起写入 trace 标签，否则 fallback 后的质量、成本和错误无法归因。
- 对非幂等工具禁止跨 provider 自动重放；工具调用只由应用层执行，模型路由层不获得业务凭据。
自托管运维
- 对模型权重、tokenizer、推理镜像和量化配置一起做不可变版本标识。
- 同时监控队列时间、首 token 延迟、tokens/s、GPU 利用率/OOM、模型加载时间和请求取消。
- 不把本地端点裸露给公网；配置服务间认证、请求大小上限、输出长度上限和每租户并发。
- 冷启动和模型下载是独立的 readiness 阶段；端口存活不等于模型可服务。