该工具采用标准 OpenAI API 协议对接自定义模型，而 LiteLLM 就是一套开源版“协议翻译+流量调度中心”。两者结合，本质是在 WorkBuddy 与 Azure 之间增加了一层标准化的代理，由网关来处理所有兼容性、容错和调度问题。 直连 Azure 的“不稳定”根源 WorkBuddy 本身支持以 OpenAI 兼容格式接入自定义模型。但直接对接 Azure OpenAI 时，工作量全部落在配置端：Azure 的鉴权用的是 api-key 请求头（不是 OpenAI 的 Bearer 令牌），且模型标识必须填“部署名称”（而非 gpt-4 家族名）。该工具自带的模型配置虽然解决了这两处差异，但无法解决网络层面的单点故障。只要 Azure 服务端出现瞬间抖动或流控限速，它就会直接报错中断。 网关的稳定机制：自动重试 + 多区域负载均衡 LiteLLM Proxy 是一个自托管的 OpenAI 兼容网关。当 WorkBuddy 通过网关调用 Azure 时，网关内置的 Router 会自动处理三个关键机制： 自动重试：单次调用失败后，LiteLLM 会在同一模型组内自动重试，默认最多 3 次。 负载均衡：若你在不同 Azure 区域（如美东、西欧）部署了同一模型，网关会自动将请求分发到可用实例。 故障转移：当一个区域的服务完全不可用时，网关会将请求切换到另一个正常区域，整个过程对 WorkBuddy 完全透明。 对应破解：这款桌面智能体只需对接 LiteLLM 网关这一个稳定端点，所有稳定性保障由网关完成。业务侧不再需要处理 API 密钥轮换、多区域切换、故障重试等复杂逻辑。 落地效果：原本 30 分钟的配置调试时间压缩到一次性完成；网络故障导致的调用失败率可降至接近零。

全链路配置分为三步：部署 LiteLLM 网关、配置 Azure 模型接入、在 WorkBuddy 中指向网关地址。标准耗时约 20-30 分钟。 第一步：部署 LiteLLM 网关（推荐 Docker Compose） 创建目录并编写 docker-compose.yml： yaml litellm: image: docker.litellm.ai/berriai/litellm:main-stable ports: - "4000:4000" environment: DATABASE_URL: "postgresql://llmproxy:dbpassword9090@db:5432/litellm" STORE_MODEL_IN_DB: "True" env_file: - .env depends_on: - db db: image: postgres:16 environment: POSTGRES_DB: litellm POSTGRES_USER: llmproxy POSTGRES_PASSWORD: dbpassword9090 在 .env 中配置 Azure 密钥： bash AZURE_API_KEY=你的Azure密钥 AZURE_API_BASE=https://你的资源名.openai.azure.com AZURE_API_VERSION=2024-10-21 第二步：配置 LiteLLM 接入 Azure 创建 config.yaml： yaml model_list: - model_name: azure-gpt-4o litellm_params: model: azure/你的部署名称 api_base: ${AZURE_API_BASE} api_key: ${AZURE_API_KEY} api_version: ${AZURE_API_VERSION} 启动网关：docker-compose up -d。LiteLLM UI 默认在 http://localhost:4000/ui。 第三步：WorkBuddy 连接 LiteLLM 网关 该工具的自定义模型通过 ~/.workbuddy/models.json 文件配置。创建或编辑该文件： json { "models": [ { "id": "gateway-azure-gpt-4o", "name": "Gateway Azure GPT-4o", "vendor": "LiteLLM", "apiKey": "sk-placeholder", "url": "http://localhost:4000/chat/completions", "maxInputTokens": 128000, "maxOutputTokens": 16384, "supportsToolCall": true, "supportsImages": true } ], "availableModels": ["gateway-azure-gpt-4o"] } 关键点：网关本身不校验 API Key，apiKey 填任意占位符即可。url 必须指向 LiteLLM 服务地址（默认 4000 端口）并包含 /chat/completions 路径。 完全退出 WorkBuddy 再重启，该应用仅启动时加载配置，不支持热重载。重启后在下拉菜单中应能看到新添加的模型。

配置完成后需经过“模型可见性→连通性→稳定性”三层验证；企业级使用建议开启数据库持久化与多模型负载均衡。 验证：三层检查法 第一层——模型是否可见：重启后打开设置→模型，下拉菜单应出现 Gateway Azure GPT-4o 条目。若看不到，检查 JSON 语法是否正确，以及文件路径是否为 ~/.workbuddy/models.json。 第二层——基础连通性：选中该模型，发送测试指令（如“用一句话介绍自己”）。若正常返回，说明 WorkBuddy ↔ LiteLLM ↔ Azure 链路已通。若返回“model not found”，检查 LiteLLM 日志：docker logs litellm 查看具体报错。最常见原因是 config.yaml 中的部署名称写错。 第三层——稳定性压测：正常使用 5-10 次后，手动模拟一次 Azure 服务抖动，观察 WorkBuddy 是否报错。LiteLLM 默认重试 3 次，单次失败后会自动尝试，用户侧几乎没有感知。 调优：企业级配置建议 多模型负载均衡：在同一个 model_name 下配置多个不同区域的 Azure 部署，LiteLLM 会自动在它们之间分发请求。 启用数据库持久化：在 Docker Compose 中已配置 PostgreSQL，Gateway 的路由规则、API Key 用量等信息都会持久化存储，不会因容器重启丢失。 按团队管控成本：LiteLLM 支持创建虚拟 Key，为不同团队设置独立的调用额度和模型权限，避免资源滥用。 自定义模型 ID 命名规范：在 models.json 中，id 和 name 建议加上 -gateway 或 -custom 后缀，避免与 WorkBuddy 内置模型命名冲突导致配置被覆盖。 长期运营：将 LiteLLM 的配置纳入版本管理（git），后续新增模型只需在 config.yaml 追加条目，重启网关即可生效，WorkBuddy 端无需任何改动。