LiteLLM Proxy 集成

概述

LiteLLM Proxy 是一个常见的 AI 网关中间件，可以让你用统一的 OpenAI 格式调用多家 API 提供商的模型。本文介绍如何在 LiteLLM Proxy 中配置 AIone 作为上游提供商。

如果你不使用 LiteLLM Proxy，而是直接调用 AIone API，请参考快速开始。

基础配置

在 LiteLLM Proxy 的 config.yaml 中添加 AIone 作为提供商：

model_list:
  # Claude 模型
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: openai/claude-sonnet-4-6
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"
 
  # GPT 模型
  - model_name: gpt-5.4
    litellm_params:
      model: openai/gpt-5.4
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"
 
  # Gemini 文本模型
  - model_name: gemini-2.5-pro
    litellm_params:
      model: openai/gemini-2.5-pro
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"

关键点：模型名前缀

model 字段必须使用 openai/ 前缀（如 openai/claude-sonnet-4-6），因为 AIone 暴露的是 OpenAI 兼容接口 /v1/chat/completions。

如果使用 anthropic/ 或 gemini/ 前缀，LiteLLM 会尝试直连 Anthropic / Google 官方 API，绕过 AIone。

Gemini 图片模型配置

Gemini 图片模型需要透传 imageConfig 等自定义参数。LiteLLM Proxy 默认不会将这些非标准字段转发给上游，需要通过 extra_body 配置。

方式一：在 config.yaml 中预设参数

适合默认参数固定的场景：

model_list:
  - model_name: gemini-image
    litellm_params:
      model: openai/gemini-3-pro-image-preview
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"
      extra_body:
        aspect_ratio: "1:1"
        image_size: "4K"

方式二：在请求体中动态传参

适合参数需要按请求变化的场景。在调用 LiteLLM Proxy 时，将自定义参数放在 extra_body 中：

{
  "model": "gemini-image",
  "messages": [
    {"role": "user", "content": "画一只穿宇航服的猫咪"}
  ],
  "max_tokens": 4096,
  "extra_body": {
    "image_size": "4K",
    "aspect_ratio": "16:9"
  }
}

也可以使用嵌套的 imageConfig 格式，两种写法等效：

{
  "model": "gemini-image",
  "messages": [
    {"role": "user", "content": "画一只穿宇航服的猫咪"}
  ],
  "max_tokens": 4096,
  "extra_body": {
    "imageConfig": {
      "aspect_ratio": "16:9",
      "image_size": "4K"
    }
  }
}

方式三：Python SDK 中使用 extra_body

from openai import OpenAI
 
# 连接你的 LiteLLM Proxy
client = OpenAI(
    api_key="sk-your-litellm-key",
    base_url="http://localhost:4000/v1",  # LiteLLM Proxy 地址
)
 
response = client.chat.completions.create(
    model="gemini-image",
    messages=[{"role": "user", "content": "画一只穿宇航服的猫咪"}],
    max_tokens=4096,
    extra_body={
        "image_size": "4K",
        "aspect_ratio": "16:9",
    },
)
 
# 文本内容
print(response.choices[0].message.content)
 
# 图片数据（如果有）
images = getattr(response.choices[0].message, "images", None)
if images:
    for img in images:
        base64_data = img["image_url"]["url"]  # data:image/jpeg;base64,...

模型命名简化

你不需要为每种分辨率创建独立的 LiteLLM 模型条目。可以只配置一个模型名，通过请求参数控制分辨率：

model_list:
  # 一个模型名，通过 image_size 参数控制分辨率
  - model_name: gemini-image
    litellm_params:
      model: openai/gemini-3-pro-image-preview
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"

请求时通过 extra_body 指定分辨率：

{"extra_body": {"image_size": "4K"}}

优先级规则： 如果同时使用了带分辨率后缀的模型名（如 -4k）和 image_size 参数，参数优先。后缀只在没传 image_size 时生效。

参考图输入

当你需要传参考图（例如图片编辑、风格迁移），建议直接传 base64 数据，不要传外部 URL：

{
  "model": "gemini-image",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "把这张图的背景换成星空"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQ..."
          }
        }
      ]
    }
  ],
  "max_tokens": 4096,
  "extra_body": {"image_size": "2K"}
}

为什么推荐 base64？

AIone 服务器（香港节点）从部分 CDN（如阿里云 CDN）下载图片可能存在网络问题或防盗链限制。base64 直接嵌入请求体，不受网络和 CDN 策略影响，是最稳定的方式。

响应格式

AIone 对 Gemini 图片模型的响应格式做了 OpenAI 兼容处理：

纯文本响应

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "这是模型的文字回复"
    }
  }]
}

含图片的响应

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "这是为你生成的图片：\n\n![image](data:image/jpeg;base64,/9j/4AAQ...)",
      "images": [
        {
          "type": "image_url",
          "index": 0,
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQ...",
            "detail": "auto"
          }
        }
      ]
    }
  }]
}

两个字段的作用：

字段	类型	说明
`content`	string	Markdown 格式的文本 + 图片，符合 OpenAI spec
`images`	array	结构化的图片数据，方便程序提取

重要： LiteLLM 的 openai/ handler 是纯直通模式，不会自动从 content 中提取图片。如果你的应用需要程序化处理图片，请使用 images 字段。

完整配置示例

以下是一个包含多种模型的完整 LiteLLM Proxy 配置：

model_list:
  # === Claude 系列 ===
  - model_name: claude-opus-4-6
    litellm_params:
      model: openai/claude-opus-4-6
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"
 
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: openai/claude-sonnet-4-6
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"
 
  # === GPT 系列 ===
  - model_name: gpt-5.4
    litellm_params:
      model: openai/gpt-5.4
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"
 
  # === Gemini 文本 ===
  - model_name: gemini-2.5-pro
    litellm_params:
      model: openai/gemini-2.5-pro
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"
 
  # === Gemini 图片 ===
  - model_name: gemini-image
    litellm_params:
      model: openai/gemini-3-pro-image-preview
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"
 
  - model_name: gemini-image-flash
    litellm_params:
      model: openai/gemini-3.1-flash-image-preview
      api_base: "https://api.openbili.com/v1"
      api_key: "sk-nex-your-key-here"

常见问题

extra_body 参数没有生效

确认你使用了正确的透传方式：

config.yaml 中：在 litellm_params 下添加 extra_body
请求体中：将参数放在顶层 extra_body 字段内
Python SDK：使用 extra_body={} 参数

LiteLLM 默认会丢弃不认识的顶层字段。所有非标准参数（image_size、aspect_ratio、imageConfig 等）必须通过 extra_body 传递。

图片生成返回 500 错误

确认 model 字段使用了 openai/ 前缀
确认 max_tokens 已设置（建议 4096）
4K 图片生成耗时较长（2-3 分钟），检查 LiteLLM Proxy 的超时设置是否足够

图片数据在哪里

content 字段：包含 Markdown 格式的图片（![image](data:...)）
images 字段：包含结构化的 base64 图片数据
LiteLLM openai/ handler 不会自动提取图片，请直接读取 images 字段

LiteLLM Proxy 超时

4K 图片生成可能需要 2-3 分钟。在 LiteLLM Proxy 配置中增加超时时间：

litellm_settings:
  request_timeout: 600  # 秒

同时建议在请求中使用 "stream": true，AIone 网关会每 10 秒发送 keepalive 心跳，防止连接被中间网络设备断开。

模型名不存在

LiteLLM litellm_params.model 中的模型名必须与 AIone 支持的模型 ID 一致
可通过 GET https://api.openbili.com/v1/models 查看完整列表
完整模型命名规则请参考模型命名与兼容规则