> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# LiteLLM

> 将 TokenLab 与 LiteLLM 结合使用，可作为 OpenAI 兼容端点或团队网关的一部分

## 概述

LiteLLM 与 TokenLab 常见有两种结合方式：

* 把 TokenLab 作为 LiteLLM 背后的 **OpenAI 兼容端点**
* 在 TokenLab 前面再放一层 LiteLLM，统一做虚拟 key、模型选择策略或额外观测

对 TokenLab 而言，最干净的默认路径是使用 LiteLLM 的 **custom OpenAI / OpenAI 兼容** 配置，并把 `api_base` 指向 `https://api.tokenlab.sh/v1`。

<Note>
  如果你明确需要 Claude-native 或 Gemini-native 请求形状，优先使用 TokenLab 自己的原生集成页，而不是强行经由 LiteLLM 的 OpenAI 兼容 抽象。
</Note>

<Note>
  **类型**: 框架或平台

  **主要路径**: OpenAI 兼容端点

  **支持级别**: 支持路径
</Note>

## 安装

```bash theme={null}
pip install 'litellm[proxy]'
```

## Proxy 配置

创建一个 `litellm-config.yaml`：

```yaml theme={null}
model_list:
  - model_name: tokenlab-gpt-5.4
    litellm_params:
      model: custom_openai/gpt-5.4
      api_base: https://api.tokenlab.sh/v1
      api_key: os.environ/OPENAI_API_KEY

  - model_name: tokenlab-claude-sonnet
    litellm_params:
      model: custom_openai/claude-sonnet-4-6
      api_base: https://api.tokenlab.sh/v1
      api_key: os.environ/OPENAI_API_KEY
```

启动代理：

```bash theme={null}
export OPENAI_API_KEY="sk-your-tokenlab-key"
litellm --config litellm-config.yaml --port 4000
```

## 通过 OpenAI SDK 调 LiteLLM

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="anything",
    base_url="http://127.0.0.1:4000"
)

response = client.chat.completions.create(
    model="tokenlab-gpt-5.4",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)
```

## 直接以 Python 库方式使用

如果你把 LiteLLM 当作 Python 库而不是 proxy 使用，同样保持 TokenLab 的 base URL：

```python theme={null}
import litellm

response = litellm.completion(
    model="custom_openai/gpt-5.4",
    api_base="https://api.tokenlab.sh/v1",
    api_key="sk-your-tokenlab-key",
    messages=[{"role": "user", "content": "Summarize this repo."}]
)
```

## 最佳实践

<AccordionGroup>
  <Accordion title="对 TokenLab 优先使用 custom_openai">
    除非你有非常明确的理由去构造更复杂的提供方映射，否则请把 TokenLab 视为 OpenAI 兼容端点。
  </Accordion>

  <Accordion title="只在确实需要额外网关层时再用 LiteLLM">
    如果你的平台自己还需要 virtual keys、模型选择策略或集中日志，LiteLLM 放在 TokenLab 前面是有价值的。
  </Accordion>

  <Accordion title="原生能力不要过度承诺">
    OpenAI 兼容 翻译层很适合广覆盖兼容，但它不是用来承诺每一个原生提供方细节都等价可用的地方。
  </Accordion>
</AccordionGroup>

## 故障排查

<AccordionGroup>
  <Accordion title="连接错误">
    * 确认 `api_base` 完全等于 `https://api.tokenlab.sh/v1`
    * 确认 LiteLLM 所在环境可以通过公网访问 TokenLab
    * 如果你在本地跑 proxy，请确认 OpenAI client 指向的是 LiteLLM 端口，而不是直接指向 TokenLab
  </Accordion>

  <Accordion title="鉴权错误">
    * 检查 LiteLLM 读取到的 `OPENAI_API_KEY` 是否正确
    * 确认 TokenLab key 以 `sk-` 开头
    * 确认该 key 已在 TokenLab dashboard 中激活
  </Accordion>

  <Accordion title="模型找不到">
    * 检查 `custom_openai/<model>` 中 TokenLab 模型名是否正确
    * 把 LiteLLM 里的 `model_name` 别名和真实 TokenLab 模型 id 分开管理
  </Accordion>
</AccordionGroup>