# LiteLLM 集成

> LiteLLM SDK 用 openai/ 或 anthropic/ 前缀加 api_base 调本平台;LiteLLM Proxy 的 config.yaml 写法

来源：https://qd.zsopc.com/docs/integrations/litellm

> [LiteLLM](https://docs.litellm.ai) 是统一多家模型调用的 Python SDK,也能部署成 OpenAI 兼容的 Proxy。本页按 LiteLLM 1.109.1(2026-11-12 发布)的官方文档核对。

## 准备 API Key

在 [qd.zsopc.com/dashboard/keys](https://qd.zsopc.com/dashboard/keys) 创建 API Key,下面的示例从环境变量读它:

```bash
export PLATFORM_API_KEY="sk-gpushare-xxx"
```

## SDK

模型名前加 `openai/`,LiteLLM 就按 OpenAI 兼容端点调用;`api_base` 要带 `/v1`:

```python
import os
import litellm

resp = litellm.completion(
    model="openai/gpt-6.1-sol",          # openai/ 后面接本平台的模型 ID
    api_base="https://qd.zsopc.com/v1",
    api_key=os.environ["PLATFORM_API_KEY"],
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(resp.choices[0].message.content)
```

`openai/` 前缀可以接本平台任何文本模型(`openai/claude-sonnet-4-6`、`openai/gemini-3.1-pro-low`、`openai/deepseek-v4.1-flash` …),非 OpenAI 模型由网关做协议翻译。

想让 Claude 走 Anthropic 原生协议,用 `anthropic/` 前缀,`api_base` **不带** `/v1`(LiteLLM 自己补 `/v1/messages`):

```python
resp = litellm.completion(
    model="anthropic/claude-sonnet-4-6",
    api_base="https://qd.zsopc.com",
    api_key=os.environ["PLATFORM_API_KEY"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
```

Responses API 同样可用:

```python
resp = litellm.responses(
    model="openai/gpt-6.1-sol",
    input="Hello",
    api_base="https://qd.zsopc.com/v1",
    api_key=os.environ["PLATFORM_API_KEY"],
)
```

## Proxy

`config.yaml`:

```yaml
model_list:
  - model_name: gpt-6.1-sol             # 客户端调用 Proxy 时用的名字
    litellm_params:
      model: openai/gpt-6.1-sol
      api_base: https://qd.zsopc.com/v1
      api_key: os.environ/PLATFORM_API_KEY
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_base: https://qd.zsopc.com
      api_key: os.environ/PLATFORM_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY   # 调用 Proxy 要带的 Key,别把 Proxy 裸露在公网
```

启动(默认监听 4000 端口):

```bash
uv tool install 'litellm[proxy]'
litellm --config config.yaml
```

或用 Docker:

```bash
docker run -v "$PWD/config.yaml:/app/config.yaml:ro" \
  -e PLATFORM_API_KEY -e LITELLM_MASTER_KEY -p 4000:4000 \
  ghcr.io/berriai/litellm:v1.109.1 --config /app/config.yaml
```

调用 Proxy:

```bash
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Hello"}]}'
```

## 注意事项

- LiteLLM 遇到它认为该模型不支持的参数时默认报错;需要放行时,在 `litellm_settings` 里设 `drop_params: true`。
- Gemini 模型建议走 `openai/` 前缀:LiteLLM 文档没有写清 `gemini/` 前缀配自定义 `api_base` 的格式。
- 所有调用都从你这把 Key 的账户余额扣积分,Proxy 侧的预算 / 限流是 LiteLLM 自己的功能,与本平台无关。

## 常见问题

| 现象 | 排查 |
|---|---|
| 404 Not Found | `openai/` 的 `api_base` 要以 `/v1` 结尾;`anthropic/` 的不带 `/v1` |
| 401 `invalid_api_key` | Key 是否复制完整(共 76 字符);`os.environ/` 引用的变量是否已导出 |
| 400 `model_not_found` | 前缀后面的模型 ID 拼写,须与 [模型列表](../reference/models.md) 一致 |
| 402 `quota_exceeded` | 余额不足。所有 Key 共享同一账户余额,到 [充值页](https://qd.zsopc.com/dashboard/billing) 充值 |

错误码完整说明见 [错误码](../reference/errors.md)。

## 相关页面

- [LangChain](./langchain.md) — Python / JS 应用框架
- [Vercel AI SDK](./vercel-ai-sdk.md) — TypeScript 应用框架
- [OpenAI SDK](../sdks/openai-sdk.md) — 直接用官方 SDK
