LiteLLM Proxy 集成

概述

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

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

基础配置

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

关键点：模型名前缀

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 中预设参数

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

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

适合参数需要按请求变化的场景。在调用 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

模型命名简化

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

请求时通过 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 配置：

常见问题

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 配置中增加超时时间：

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

模型名不存在

LiteLLM litellm_params.model 中的模型名必须与 AIone 支持的模型 ID 一致

可通过 GET https://api.nexara.net/v1/models 查看完整列表

完整模型命名规则请参考模型命名与兼容规则

LiteLLM Proxy 集成

概述#

基础配置#

关键点：模型名前缀#

Gemini 图片模型配置#

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

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

方式三：Python SDK 中使用 extra_body#

模型命名简化#

参考图输入#

响应格式#

纯文本响应#

含图片的响应#

完整配置示例#

常见问题#

extra_body 参数没有生效#

图片生成返回 500 错误#

图片数据在哪里#

LiteLLM Proxy 超时#

模型名不存在#

概述