多模型接入与成本可观测 部分实测

场景

项目接了多个模型供应商（OpenAI/Anthropic/国产模型），痛点不在模型本身，而在「接入面」：每个服务各配一套 key、各自直连供应商，成本散落不可见，切换与限流全靠手改。你想要的是一条确定性链路：一个入口接所有模型 + 调用/成本/延迟一目了然。

本组合包把「接入 → 观测」串起来：litellm 网关做统一入口（一个 base_url 接所有模型，key 集中管理）、logfire 做 OpenTelemetry 可观测（调用/成本/延迟一目了然）。两个工具各管一段，不重复。

组合成员 （2）

python3 -m venv ~/.litellm-venv
~/.litellm-venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple litellm[proxy]

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0
logfire --version

方案总览

备选方案：只要「统一入口」→ 只装 litellm；只要「成本观测」→ 只装 logfire。顺序逻辑：先网关（入口）→ 再观测（数据流方向）。litellm 为服务端进程，logfire 为 SDK/CLI 形态，写面互不重叠。

快速开始

一键脚本由本文档自动生成（渲染后位于 pages/combos/combo-model-access.sh），逐条执行：

bash pages/combos/combo-model-access.sh

• 装完你会得到：litellm 统一网关（端口 4000，OpenAI 兼容）+ logfire 可观测接入。
• 预计耗时：5-10 分钟。最大卡点 = litellm 安装（依赖多，实测清华镜像 venv 安装约 80s）。
• 前置条件：Python >= 3.8；真实转发需各模型 API key（key 集中放 litellm 配置，客户端不再散落）。

想弄明白每一步在干什么、装错了怎么恢复 → 看「逐步教学」。一键脚本出问题 → 按逐步教学手动执行定位。

逐步教学

第 1 步：装 litellm（统一接入网关）

litellm 解决「接入面」：一个 OpenAI 兼容 base_url 接所有模型，key 集中管理、切换与限流在网关层统一处理。它依赖多（建议隔离 venv，实测清华镜像安装约 80s）；首次启动拉取远程 cost map 超时会自动回退本地备份（国内网络观察，实测）。

python3 -m venv ~/.litellm-venv
~/.litellm-venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple litellm[proxy]

预期输出: pip 安装完成；~/.litellm-venv/bin/litellm --version 可输出版本号

装好确认：

• ~/.litellm-venv/bin/litellm --version 输出版本号（>= 1.98.0）；
• 起 proxy 后 curl http://localhost:4000/health/liveliness 返回 "I'm alive!"（实测）。

卡住怎么办：

• 安装慢（80s 量级）→ 正常；超时重试一次（命令已带清华镜像）。
• 首次启动拉 cost map 超时 → 自动回退本地备份，不影响启动（实测观察）。
• 端口 4000 被占 → 启动参数 --port <其它端口>。

第 2 步：装 logfire（可观测）

logfire 做 OpenTelemetry 可观测：调用/成本/延迟一目了然。SDK/CLI 形态，安装即用；接入方式按官方文档配置后，litellm 的调用数据可经 OpenTelemetry 进 logfire。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0
logfire --version

预期输出: logfire 版本号 4.41.0

装好确认：

• logfire --version 输出版本号；
• 按官方文档完成初始化（logfire auth / 环境变量配置，以官方为准）。

卡住怎么办：

• pip 超时 → 命令已带清华镜像，重试一次。
• 接入 litellm 数据 → 按官方 OpenTelemetry 接入文档配置（本组合未实测衔接面，见验证证据）。

装完验收（一步到位）

作用：装完跑下面一条命令块，全绿 = 本组合包就绪；某条失败 → 回「逐步教学」对应步骤定位。

~/.litellm-venv/bin/litellm --version
logfire --version

预期输出: litellm >= 1.98.0；logfire 4.41.0。命令面全绿 = 就绪；真实转发验收：配置 key 后起 proxy，curl http://localhost:4000/health/liveliness 返回 "I'm alive!"（实测）

注：多模型真实转发需各模型 API key（key 集中放 litellm 配置），未实测已标注。

日常使用

启动与入口

• litellm：~/.litellm-venv/bin/litellm --config <配置文件>（默认端口 4000，OpenAI 兼容 base_url = http://localhost:4000）。
• logfire：SDK 在代码里接入；CLI 查看面板/状态。

常用操作

1. 客户端统一接入：base_url 指向 litellm 网关，key 用 litellm 管理的 key，不再散落各家。
2. 换模型/限流：改 litellm 配置（网关层统一处理），客户端无感。
3. 看成本：logfire 面板看调用/成本/延迟。

数据与目录

• litellm：venv 在 ~/.litellm-venv/；配置与 key 在你自己指定的 config 文件（注意密钥权限）。
• logfire：遥测数据走 OpenTelemetry 出口，本地无大文件。

卸载与清理

按安装相反顺序卸载：

pip uninstall -y logfire
rm -rf ~/.litellm-venv

提示：litellm 配置里的 API key 记得一并删除或妥善保管（明文在配置文件里）。

安装顺序

1. litellm（网关）→ 2. logfire（可观测）；全装完跑通才算组合就绪。litellm 为服务端进程（默认端口 4000），logfire 为 SDK/CLI 形态。

依赖警告

• 版本：Python >= 3.8（两工具 pip 形态）；litellm >= 1.98.0（实测）；logfire == 4.41.0。
• 环境：litellm 建议隔离 venv（依赖多）；litellm 首次启动拉取远程 cost map 超时会自动回退本地备份（国内网络观察，2026-08-29 实测）。
• 端口：litellm 默认 4000（--port 可改）；与占用 4000 的服务冲突。
• 冲突：两工具写面互不重叠（代理配置 / 遥测数据）→ compatible（组合包实测态：2026-08-29 litellm 代理面冒烟通过）。
• 国内网络：pip → 清华镜像；litellm 远程 cost map 国内可能超时（自动回退本地备份）。
• 注意：真实转发需模型 API key（key 集中放 litellm 配置，客户端不再散落）。

FAQ

1. litellm 装得慢正常吗？ → 正常，依赖多（实测清华镜像约 80s）；建议隔离 venv，超时重试一次。
2. litellm 启动时拉取 cost map 超时？ → 自动回退本地备份，不影响启动（实测观察）。
3. 端口 4000 被占？ → --port 换端口；客户端 base_url 同步改。
4. 完整链路（网关→观测串跑）实测过吗？ → litellm 代理面已实测（mock 模型 + /health/liveliness + /v1/models 注册）；真实 key 转发 + logfire 遥测衔接待组合包验收时补测。

验证证据

每份组合包在隔离环境实测（冒烟 + 写面检查），未实测项在文中如实标注；实测日期见下方验证证据。

验证于 2026-08-29 · TTL 到期 —（180 天）

• 2026-08-29：litellm 1.98.0 实测（清华镜像 venv 安装 80s；openai/mock + dummy key 起 proxy：/health/liveliness "I'm alive!" + /v1/models mock-gpt 注册成功；server 正常停止）——实测复现日志（2026-08-29）。
• 2026-08-28：logfire 收录实测（安装/命令面）。
• 未实测（如实标注）：完整链路（网关→观测串跑）待组合包验收时实测（litellm 代理面已验证，衔接面 = 真实 key 转发 + logfire 遥测接入）。

关联问题

• ollama-connect-failed
• open-webui-ollama-connect