AI 适配器完整指南 — 基于 litellm 统一接口调用 100+ LLM 提供商，无需手写 HTTP。

---

Quick Reference

属性	值
适配器名称	ai
平台标识	ai
协议	litellm（REST）
类	AIAdapter
导入	from ncatbot.adapter.ai import AIAdapter
功能	Chat Completion / Embeddings / Image Generation / ASR 语音识别 / MCP 工具调用

# 最小配置
adapters:
  - type: ai
    platform: ai
    config:
      api_key: "sk-xxxx"
      completion_model: "gpt-4"

---

简介

AI 适配器是一个纯 API 调用型适配器，不产生事件、不需要显式启动外部服务。它通过 litellm 统一接口，让你在插件中直接调用 OpenAI、Anthropic、DeepSeek、通义千问、Kimi、Gemini 等 100+ LLM 提供商的 API。

核心能力：

功能	方法	说明
Chat Completion	api.ai.chat()	对话 / 文本生成
Embeddings	api.ai.embeddings()	文本向量化
Image Generation	api.ai.image_generation()	图像生成
ASR	api.ai.transcription()	语音转文字

---

认证方式

AI 适配器支持两种认证方式，可混合使用：

方式一：config.yaml 配置

adapters:
  - type: ai
    platform: ai
    config:
      api_key: "sk-xxxx"
      base_url: "https://api.deepseek.com"   # 可选，自定义端点

方式二：环境变量

litellm 自动读取对应提供商的环境变量，无需在配置文件中写 API Key：

# OpenAI
export OPENAI_API_KEY="sk-xxxx"

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-xxxx"

# DeepSeek
export DEEPSEEK_API_KEY="sk-xxxx"

# Azure OpenAI
export AZURE_API_KEY="xxxx"
export AZURE_API_BASE="https://xxx.openai.azure.com/"

# Gemini
export GEMINI_API_KEY="xxxx"

提示

环境变量方式更安全 — 避免将 API Key 写入配置文件提交到版本控制。

---

配置项详解

adapters:
  - type: ai
    platform: ai
    enabled: true
    config:
      # 认证
      api_key: ""                          # API Key（空则读取环境变量）
      base_url: ""                         # 自定义 API 端点

      # 各功能默认模型
      completion_model: "gpt-4"            # Chat Completion 默认模型
      embedding_model: "text-embedding-3-small"  # Embedding 默认模型
      image_model: "dall-e-3"              # 图像生成默认模型
      asr_model: ""                        # ASR 语音识别默认模型

      # 通用参数
      timeout: 120.0                       # 请求超时（秒）
      max_tokens: null                     # 默认最大 token 数

      # MCP 服务器（可选，让模型调用外部工具）
      mcp_servers:
        weather:
          transport: "http"                # http | sse | stdio（缺省自动判断）
          url: "https://mcp.weather.com/mcp"
          headers: {}                      # 可选请求头
        github:
          transport: "stdio"
          command: "npx"
          args: ["-y", "@mcp/github"]
          env: {}                          # 可选环境变量

配置项说明

配置项	类型	默认值	说明
api_key	string	""	API Key，空时由 litellm 从环境变量读取
base_url	string	""	自定义 API 端点（国内 LLM 必需）
completion_model	string	""	Chat Completion 默认模型
embedding_model	string	""	Embedding 默认模型
image_model	string	""	图像生成默认模型
asr_model	string	""	ASR 语音识别默认模型
timeout	float	120.0	HTTP 请求超时（秒）
max_tokens	int | null	null	默认最大生成 token 数
mcp_servers	dict	{}	MCP 服务器配置（详见下文"MCP 工具调用"）

模型覆盖规则

每个 API 调用都可以通过 model= 参数覆盖配置中的默认模型：

# 使用默认的 completion_model
resp = await self.api.ai.chat("你好")

# 临时切换到其他模型
resp = await self.api.ai.chat("你好", model="deepseek-chat")

如果指定的模型不存在，适配器会自动回退到配置中的默认模型。

---

基本用法

Chat Completion

# 简单对话（传入字符串自动包装为 messages）
resp = await self.api.ai.chat("请介绍一下 Python")
print(resp.choices[0].message.content)

# 自定义 messages（多轮对话）
resp = await self.api.ai.chat([
    {"role": "system", "content": "你是一个友好的助手"},
    {"role": "user", "content": "你好！"},
])
print(resp.choices[0].message.content)

# 直接传入 MessageArray（支持图文混合）
resp = await self.api.ai.chat(event.message)  # 用户发的消息直接传入
await event.reply(resp.choices[0].message.content)

# 指定模型和参数
resp = await self.api.ai.chat(
    "写一首诗",
    model="deepseek-chat",
    temperature=0.8,
    max_tokens=200,
)

MessageArray 支持

chat() 和 chat_text() 可以直接接受 MessageArray 或单个 MessageSegment，适配器会自动转换为 AI 可理解的格式：

消息段	转换结果	说明
PlainText	文本	直接保留
Image	图片 URL	支持 URL / base64 / 本地路径
At	@{user_id}	可通过 nickname_map 显示昵称
Reply	[回复消息 id=...]	转为文本提示
其他（Video/File/Record等）	跳过	记录警告日志

# 图文混合对话：用户发送图片 + 文字，直接传给 AI
text = await self.api.ai.chat_text(event.message)
await event.reply(text)

# 使用 nickname_map 让 AI 看懂 @昵称
text = await self.api.ai.chat_text(
    event.message,
    nickname_map={"12345": "小明", "67890": "小红"},
)

Embeddings

# 单文本嵌入
resp = await self.api.ai.embeddings("这是一段文本")
vector = resp.data[0].embedding  # List[float]

# 批量嵌入
resp = await self.api.ai.embeddings(["文本1", "文本2", "文本3"])
for item in resp.data:
    print(len(item.embedding))  # 向量维度

Image Generation

# 生成图片
resp = await self.api.ai.image_generation(
    "一只在编程的猫",
    size="1024x1024",
)
image_url = resp.data[0].url
print(image_url)

ASR 语音转文字

# 从文件对象识别
with open("audio.mp3", "rb") as f:
    text = await self.api.ai.transcription_text(file=f)

# 指定语言提高准确率
with open("audio.mp3", "rb") as f:
    text = await self.api.ai.transcription_text(file=f, language="zh")

ASR 模型配置

ASR 需要在配置中指定 asr_model，例如 SiliconFlow：asr_model: "openai/TeleAI/TeleSpeechASR"

Sugar 便捷方法

如果只需要文本、图片或语音识别文本，可以用更简洁的 sugar 方法：

# chat_text() — 直接拿到回复文本（str）
text = await self.api.ai.chat_text("你好")
print(text)  # "你好！有什么可以帮你的？"

# 也可以直接传 MessageArray
text = await self.api.ai.chat_text(event.message)

# generate_image() — 直接拿到 Image 消息段，可直接放入 MessageArray
image = await self.api.ai.generate_image("一只在编程的猫", size="1024x1024")
await event.reply(image)  # 直接发送图片

# transcription_text() — 音频转纯文本
with open("audio.mp3", "rb") as f:
    text = await self.api.ai.transcription_text(file=f)
print(text)  # "大家好，欢迎来到今天的直播..."

---

MCP 工具调用

MCP (Model Context Protocol) 让模型在对话中调用外部工具（查天气、搜网页、操作 GitHub 等）。配置 mcp_servers 后，chat() 会自动加载工具并把工具执行结果回传给模型，形成"请求工具 → 执行 → 回传 → 继续对话"的循环，直到模型给出最终回答。

依赖

需安装 mcp Python SDK。AI 适配器启动时自动检查安装，或手动 pip install "mcp>=1.25.0,<2.0.0"。

配置格式

mcp_servers 是 {服务器名: 配置} 字典，格式与 LiteLLM MCP 兼容：

传输	适用	必需	可选
http	Streamable HTTP（现代标准，默认）	url	headers
sse	旧版 Server-Sent Events	url	headers
stdio	本地子进程（npx / uvx / python）	command	args、env

adapters:
  - type: ai
    config:
      completion_model: "gpt-4"
      mcp_servers:
        deepwiki:                       # http 服务器
          transport: "http"
          url: "https://mcp.deepwiki.com/mcp"
        github:                         # stdio 服务器
          transport: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-github"]
          env: { GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx" }

transport 缺省自动判断：有 command → stdio；有 url → http。多个服务器的工具按 {服务器名}_{工具名} 前缀区分，避免同名冲突（如 GitHub 的 create_issue → github_create_issue）。

使用方式

配置后 chat() 无需额外参数即可使用工具（默认读取 config）：

resp = await self.api.ai.chat("给我看看 deepwiki 上关于 MCP 的首页内容")
print(resp.choices[0].message.content)

也可临时覆盖服务器配置，或用 max_tool_calls（默认 10）限制单轮工具调用轮数：

resp = await self.api.ai.chat(
    "查询北京的天气",
    mcp_servers={"weather": {"transport": "http", "url": "https://mcp.weather.com/mcp"}},
    max_tool_calls=5,
)

模型不调用工具通常是模型不支持 function calling 或未配置 mcp_servers；工具报错时检查 url/command 与 headers/env。单个服务器连接失败不影响其他服务器，可查看日志中 MCP 服务器 xxx 连接失败 信息。

---

返回值结构

AI 适配器直接返回 litellm 的响应对象，以下是主要结构说明。

ModelResponse（Chat Completion 返回值）

ModelResponse(
    id="chatcmpl-xxx",              # 请求唯一标识
    choices=[
        Choices(
            finish_reason="stop",    # "stop" | "length" | "tool_calls"
            index=0,
            message=Message(
                content="回复内容",   # 模型生成的文本
                role="assistant",
            ),
        )
    ],
    created=1234567890,              # Unix 时间戳
    model="gpt-4",                   # 实际使用的模型名
    usage=Usage(
        prompt_tokens=10,            # 输入 token 数
        completion_tokens=20,        # 输出 token 数
        total_tokens=30,             # 总 token 数
    ),
)

快速取值：

resp = await self.api.ai.chat("你好")
text = resp.choices[0].message.content       # 回复文本
tokens = resp.usage.total_tokens             # 总 token 数
model_used = resp.model                      # 实际模型名

EmbeddingResponse（Embeddings 返回值）

EmbeddingResponse(
    model="text-embedding-3-small",
    data=[
        Embedding(
            embedding=[0.1, -0.2, ...],  # 向量（List[float]）
            index=0,
        )
    ],
    usage=Usage(
        prompt_tokens=5,
        total_tokens=5,
    ),
)

ImageResponse（Image Generation 返回值）

ImageResponse(
    created=1234567890,
    data=[
        ImageObject(
            url="https://...",       # 图片 URL
            b64_json=None,           # 或 Base64 编码的图片数据
            revised_prompt="...",    # 修正后的提示词
        )
    ],
)

---

支持的模型提供商

通过 litellm，AI 适配器支持以下提供商（部分列表）：

提供商	模型名前缀/格式	示例
OpenAI	gpt-*	gpt-4, gpt-4o, gpt-3.5-turbo
Anthropic	claude-*	claude-3-opus-20240229
DeepSeek	deepseek/* 或自定义 base_url	deepseek/deepseek-chat
通义千问	qwen/*	qwen/qwen-turbo
Kimi	自定义 base_url	通过 base_url 配置
Google Gemini	gemini/*	gemini/gemini-pro
Azure OpenAI	azure/*	azure/gpt-4
AWS Bedrock	bedrock/*	bedrock/anthropic.claude-3

完整支持列表参见 litellm 文档。

国内 LLM 配置示例

# DeepSeek
adapters:
  - type: ai
    config:
      api_key: "sk-xxxx"
      base_url: "https://api.deepseek.com"
      completion_model: "deepseek-chat"

# 通义千问（兼容 OpenAI 格式）
adapters:
  - type: ai
    config:
      api_key: "sk-xxxx"
      base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
      completion_model: "qwen-turbo"

---

模型验证

适配器启动时会自动验证配置的默认模型：

• 检查模型所需的环境变量是否已设置
• 验证失败时输出警告日志，但不阻止启动
• API 调用时若模型不存在，自动回退到默认模型

---

常见问题

问题	原因	解决方案
未指定模型 报错	未配置默认模型且调用时未传 model=	配置 completion_model 或调用时指定 model=
API Key 无效	Key 过期或不正确	检查配置或环境变量中的 API Key
模型不存在	模型名拼写错误或提供商不支持	参考提供商文档确认模型名
超时	网络不通或模型响应慢	增大 timeout 或检查网络
国内 LLM 调不通	未配置 base_url	配置对应提供商的 API 端点

---

示例

• examples/ai/01_hello_world/ — 最简 AI 对话 Bot
• examples/ai/02_mcp_tools/ — MCP 工具调用（模型自动调用外部工具）

---

延伸阅读

• AI Bot API 参考 → reference/bot_api/ai/
• 多平台开发 → multi_platform/
• 适配器接口参考 → reference/adapter/

版权所有

版权归属：GEYUANwuqi

许可证：署名 4.0 国际 (CC-BY-4.0)