1. 为什么要在 OpenWebUI 前面加一层 LiteLLM如果你正在自建 AI 对话入口大概率遇到过这种局面OpenWebUI 界面确实好用但模型来源太杂。阿里云百炼的 Coding Plan 走一套密钥本地 Ollama 又是另一套地址哪天想再加个别的云端模型又得回到 OpenWebUI 里改连接、改参数前端配置越堆越乱。我试过直接把百炼的地址填进 OpenWebUI能跑但问题很快暴露模型名要手动对齐控制台、密钥散落在前端、调用日志看不到、想给不同同事分配不同模型权限基本没法做。后来把 LiteLLM 插在中间OpenWebUI 只认一个 OpenAI 兼容入口后端接百炼还是接 Ollama 由 LiteLLM 决定整个链路一下子清爽了。这篇就聚焦一件事OpenWebUI 通过 LiteLLM 接入阿里云百炼 Coding Plan 的完整配置路径。会给出 LiteLLM 的 config.yaml 骨架、docker-compose 里 PostgreSQL 与网络的关键写法、OpenWebUI 的连接参数以及一次模型列表拉取和对话请求的验证动作。适合已经在跑 OpenWebUI、想统一管理多模型资源的开发者。如果你还没搭 OpenWebUI也可以先看配置部分思路是通用的。需要说明的是百炼 Coding Plan 的密钥格式是 sk-sp-xxx 这类专属密钥和普通 DashScope Key 不是一回事配置时别填错。下面所有步骤都围绕这个前提展开。2. 前置准备TaoToken 统一 Key 与 API 通道在动手写 config.yaml 之前先把密钥和通道这件事理清楚。很多接入失败不是配置写错而是密钥来源和 API 地址没对齐。TaoToken 在这里的角色是统一 Key 与 API 通道。你可以把它理解成一个钥匙串百炼 Coding Plan、本地 Ollama、后续可能加的其它模型都可以通过同一套通道去管理访问凭证避免每个模型单独维护一份密钥。对于自建对话入口的开发者来说这能省掉大量在多个控制台之间来回切换的时间。具体操作上先到官网了解整体能力再进控制台创建 API Key。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 控制台入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。API 基础地址统一用 https://taotoken.net/api 注意这个地址不带 UTM 参数配置里直接写它。创建好 Key 之后建议先在文档页确认一下当前支持的模型名和调用格式文档入口是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这一步别跳过因为百炼 Coding Plan 的模型名会随控制台更新比如 qwen3-max-2026-01-23 这种带日期的版本号写错了 LiteLLM 会直接报模型不存在。注意TaoToken 的 API Key 和百炼控制台里的 sk-sp-xxx 是两套东西。前者用于统一通道后者是百炼侧专属密钥。配置 LiteLLM 时如果走 TaoToken 通道api_key 填 TaoToken 的 Key如果直连百炼才填 sk-sp-xxx。两者不要混用。如果你更习惯用命令行管理密钥API Keys 页面可以直接生成和吊销入口是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后先复制保存页面刷新后通常不再完整显示。3. LiteLLM config.yaml 骨架与 docker-compose 配置这一节是核心。LiteLLM 的配置文件决定了请求怎么转发docker-compose 决定了容器之间能不能互相访问。两块都要写对。3.1 config.yaml 的模型列表写法先看 config.yaml 骨架。关键点是每个模型配置必须以-开头缩进层级要一致否则 LiteLLM 只会加载最后一个模型——这是最常见的坑。model_list: - model_name: lite-cdp-qwen3-max-2026-01-23 litellm_params: model: openai/qwen3-max-2026-01-23 api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: lite-cdp-qwen3.5-plus litellm_params: model: openai/qwen3.5-plus api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: qwen-8b-local litellm_params: model: ollama/qwen2.5:8b api_base: http://host.docker.internal:11434 - model_name: llama3-local litellm_params: model: ollama/llama3 api_base: http://host.docker.internal:11434 general_settings: store_model_in_db: true master_key: os.environ/LITELLM_MASTER_KEY litellm_settings: drop_params: true几个参数解释一下。model_name是 OpenWebUI 里显示的名字可以自定义建议加个前缀方便区分来源比如 lite-cdp- 表示百炼 Coding Plan。model字段里的openai/前缀表示用 OpenAI 兼容格式调用ollama/表示走 Ollama 协议。api_base走 TaoToken 通道时统一填 https://taotoken.net/api 本地 Ollama 则用 host.docker.internal 指向宿主机。store_model_in_db: true这个开关很重要开启后 LiteLLM 会把模型配置存进数据库之后可以在管理界面动态增删模型不用每次改文件重启。drop_params: true用于丢弃部分模型不支持的参数避免因为参数不兼容导致请求失败。3.2 docker-compose 里的 PostgreSQL 与网络LiteLLM 需要 PostgreSQL 做持久化存密钥、日志、模型配置。容器网络必须让 OpenWebUI、LiteLLM、PostgreSQL 在同一个网络里否则 OpenWebUI 访问不到 LiteLLM。services: postgres: image: postgres:16 environment: POSTGRES_USER: litellm POSTGRES_PASSWORD: litellm_pass POSTGRES_DB: litellm volumes: - pg_data:/var/lib/postgresql/data networks: - ai-network litellm: image: ghcr.io/berriai/litellm:main-latest ports: - 4000:4000 environment: DATABASE_URL: postgresql://litellm:litellm_passpostgres:5432/litellm LITELLM_MASTER_KEY: sk-1234567890 STORE_MODEL_IN_DB: True TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} volumes: - ./config.yaml:/app/config.yaml command: [--config, /app/config.yaml, --port, 4000] depends_on: - postgres networks: - ai-network volumes: pg_data: networks: ai-network: external: true这里networks声明为 external: true意思是这个网络已经存在compose 不再创建直接加入。如果你的 OpenWebUI 也在同一个 compose 里把它的服务也加上networks: - ai-network即可。如果 OpenWebUI 是单独部署的需要手动把它连到这个网络命令是docker network connect ai-network openwebui容器名。DATABASE_URL里的主机名是 postgres这是容器名同一网络内可以直接解析。LiteLLM 启动时会自动跑 Prisma 迁移建表不需要手动初始化只要 DATABASE_URL 正确看日志出现迁移成功即可。4. OpenWebUI 连接参数与验证请求配置写完启动容器接下来是 OpenWebUI 侧的连接和验证。4.1 OpenWebUI 添加 LiteLLM 连接进入 OpenWebUI 设置找到连接Connections部分新增一个 OpenAI 兼容连接。URL 填http://litellm-proxy:4000注意这里用的是容器名前提是 OpenWebUI 和 LiteLLM 在同一 Docker 网络。如果你给 LiteLLM 服务起的名字不是 litellm-proxy换成实际容器名。密钥填 LiteLLM 里创建的 Virtual Key不是 master key。保存后OpenWebUI 的模型下拉列表会自动拉取 LiteLLM 代理的所有模型。如果列表为空先检查网络连通性再检查密钥是否正确。4.2 拉取模型列表验证在宿主机上先做一次模型列表拉取确认 LiteLLM 本身工作正常curl -s http://localhost:4000/v1/models \ -H Authorization: Bearer sk-1234567890 | jq .data[].id返回结果里应该能看到 config.yaml 里配置的所有 model_name比如 lite-cdp-qwen3-max-2026-01-23、qwen-8b-local 等。如果只返回一个模型回去检查 config.yaml 的缩进大概率是-开头漏了。4.3 发一次对话请求模型列表正常后发一次实际对话请求curl -s http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-1234567890 \ -H Content-Type: application/json \ -d { model: lite-cdp-qwen3-max-2026-01-23, messages: [{role: user, content: 用一句话说明什么是模型网关}] } | jq .choices[0].message.content能收到正常回复说明 LiteLLM 到百炼 Coding Plan 的链路通了。然后回到 OpenWebUI 界面在模型下拉里选同一个模型发一条消息确认前端也能正常对话。两步都通过整个接入就算完成。LiteLLM 自带管理界面地址是 http://localhost:4000/ui 登录后可以查看所有模型、Virtual Key 和调用日志。日志里能看到每次请求的 token 消耗方便做成本分析。5. 本篇常见错误排查接入过程中踩的坑基本集中在下面几类对照排查能省不少时间。URL 混淆导致 invalid_access_token。百炼有国内版和国际版域名写错会直接返回鉴权失败。国内版用 coding.dashscope.aliyuncs.com/v1国际版是 coding-intl 开头。判断方法很简单先用 curl 直接测一次哪个域名能通就用哪个。走 TaoToken 通道时则统一用 https://taotoken.net/api 不要混填百炼域名。YAML 缩进错误导致只加载最后一个模型。这是最高频的问题。config.yaml 里每个模型配置必须是列表项以-开头且model_name和litellm_params的缩进层级要一致。改完可以用python -c import yaml; yaml.safe_load(open(config.yaml))快速校验语法。容器网络隔离OpenWebUI 访问不到 LiteLLM。表现是 OpenWebUI 里连接测试失败或模型列表拉不到。检查两个容器是否在同一网络用docker network inspect ai-network看成员列表。不在的话把 OpenWebUI 服务加进同一个网络或手动 connect。Ollama 访问失败。LiteLLM 容器内访问宿主机 Ollamaapi_base 要用 http://host.docker.internal:11434 。这个地址在 Docker for Mac/Windows 上可用Linux 环境下需要额外配置 host-gateway或者在 compose 里加extra_hosts: - host.docker.internal:host-gateway。数据库初始化担心。不用手动建表LiteLLM 启动时自动跑迁移。如果启动报数据库连接错误检查 DATABASE_URL 里的用户名、密码、库名是否和 postgres 服务一致以及 postgres 是否已经就绪depends_on 只保证启动顺序不保证就绪必要时加重试。模型名与控制台不一致。百炼 Coding Plan 的模型名带版本日期比如 qwen3-max-2026-01-23必须和控制台实际名称完全一致。写错会报模型不存在。建议每次配置前先去控制台复制准确名称。6. 后续怎么扩展与统一管理这套架构跑通之后扩展成本很低。想加新模型只需在 LiteLLM 的 config.yaml 里加一段配置或者在管理界面动态添加OpenWebUI 侧完全不用改。本地 Ollama 和云端百炼可以同时存在按需在对话时切换。权限管理上LiteLLM 的 Virtual Key 功能可以给不同用户或团队分配不同的模型访问权限还能设置预算和速率限制。对于团队内部统一管理多模型资源的场景这比在每个前端单独配密钥要可控得多。如果你后续要接更多模型或者想把编码类任务单独走一条通道可以了解下 Coding Plan 的用法入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要直接调试模型对话效果的话模型对话页面在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。接入过程中遇到鉴权或转发问题优先查 API Keys 和接入文档这两个页面覆盖了大部分配置细节。最后提醒一句config.yaml 改完记得重启 LiteLLM 容器store_model_in_db开启后虽然支持动态管理但文件里的静态配置仍需重启才生效。验证顺序永远是先 curl LiteLLM再测 OpenWebUI这样出问题能快速定位是哪一层。