lunanting/ai-chatbot

Fork 0

Your Name 53ddb7e585

Lint / build (20) (push) Has been cancelled

Details

Playwright Tests / test (push) Has been cancelled

Details

Initial commit - clean repository

2025-12-17 20:15:18 +08:00

9.9 KiB

Raw Blame History

AI 供应商配置指南

概述

本系统支持多种 AI 供应商的动态配置，所有供应商都使用 OpenAI 兼容的 API 格式，但根据不同供应商的特点进行了优化。

支持的供应商类型

1. 阿里云 (alibaba)

适用场景： 通义千问系列模型（Qwen）

配置示例：

{
  "name": "阿里云通义千问",
  "type": "alibaba",
  "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "apiKey": "sk-xxxxxxxxxxxxxxxx"
}

可用模型：

qwen-turbo - 快速响应，适合日常对话
qwen-plus - 更强性能，适合复杂任务
qwen-max - 最强性能
qwen-vl-plus - 支持图像输入的多模态模型
qwen3-vl-plus - 最新多模态模型

特点：

完全兼容 OpenAI Chat Completions API
支持流式响应 (stream: true)
支持 Function Calling
支持多模态输入（图片、视频）

请求示例：

POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "model": "qwen-plus",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手"},
    {"role": "user", "content": "你好"}
  ],
  "stream": true
}

2. OpenAI 官方 (openai)

适用场景： OpenAI 官方模型（GPT-4、GPT-3.5 等）

配置示例：

{
  "name": "OpenAI 官方",
  "type": "openai",
  "baseUrl": "https://api.openai.com/v1",
  "apiKey": "sk-proj-xxxxxxxxxxxxxxxx"
}

可用模型：

gpt-4-turbo - GPT-4 Turbo
gpt-4 - GPT-4
gpt-3.5-turbo - GPT-3.5 Turbo
o1 - 推理模型
o1-mini - 轻量推理模型

特点：

标准 OpenAI API
支持所有官方功能
支持 Function Calling、Vision、Audio

请求示例：

POST https://api.openai.com/v1/chat/completions
Authorization: Bearer sk-proj-xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "model": "gpt-4-turbo",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Hello"}
  ]
}

3. OpenAI 兼容 (custom)

适用场景： 任何提供 OpenAI 兼容 API 的第三方服务

配置示例：

{
  "name": "GPT-5 Nano",
  "type": "custom",
  "baseUrl": "https://api.huandutech.com/v1",
  "apiKey": "sk-xxxxxxxxxxxxxxxx"
}

典型的兼容服务：

Claude via OpenRouter
GPT-5 Nano 等第三方优化模型
本地部署的 OpenAI 兼容服务（如 vLLM、Text Generation WebUI）
Azure OpenAI Service
Cloudflare Workers AI

请求格式：

POST <baseUrl>/chat/completions
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "model": "<model_name>",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "stream": true  // 可选
}

兼容性要求：

必需端点： /chat/completions 或 /v1/chat/completions
必需请求头： Authorization: Bearer <apiKey>
请求格式： 符合 OpenAI Chat Completions API 规范
响应格式： 返回标准 OpenAI 格式的 JSON 响应

完整请求示例：

{
  "model": "gpt-5-nano",
  "messages": [
    {
      "role": "system",
      "content": "你是一个有帮助的助手。"
    },
    {
      "role": "user",
      "content": "你能做什么？"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 2000,
  "stream": true,
  "top_p": 1,
  "frequency_penalty": 0,
  "presence_penalty": 0
}

系统设置配置步骤

1. 添加 AI 供应商

登录管理员账户
进入 系统设置 → AI 提供商
点击 添加提供商
填写信息：
- 名称： 供应商显示名称（如"阿里云通义千问"）
- 类型： 选择 alibaba / openai / custom
- Base URL： API 基础地址
- API Key： 您的 API 密钥
点击保存

2. 添加 AI 模型

在 系统设置 → AI 模型 中
点击 添加模型
填写信息：
- 供应商： 选择刚创建的供应商
- 模型 ID： 模型的实际标识符（如 qwen-plus、gpt-4）
- 显示名称： 前端显示的名称（如"通义千问 Plus"）
- 描述： 模型的简要说明
- 支持视觉： 是否支持图像输入
- 默认模型： 是否设为系统默认
- 排序顺序： 前端显示的顺序
点击保存

3. 测试配置

返回聊天界面
在模型选择器中应该能看到新配置的模型
选择模型并发送测试消息
查看服务器日志确认请求正常

API 请求格式详解

所有供应商都遵循 OpenAI Chat Completions API 规范：

基本请求结构

interface ChatCompletionRequest {
  model: string;              // 模型 ID
  messages: Message[];        // 消息列表
  temperature?: number;       // 0-2，控制随机性
  max_tokens?: number;        // 最大生成 token 数
  stream?: boolean;           // 是否流式响应
  top_p?: number;            // 核采样参数
  frequency_penalty?: number; // 频率惩罚
  presence_penalty?: number;  // 存在惩罚
  stop?: string | string[];   // 停止序列
}

interface Message {
  role: "system" | "user" | "assistant" | "tool";
  content: string | ContentPart[];
  name?: string;
  tool_calls?: ToolCall[];
}

多模态输入（支持的模型）

{
  "model": "qwen-vl-plus",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "这张图片里有什么？"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg"
          }
        }
      ]
    }
  ]
}

Function Calling

{
  "model": "qwen-plus",
  "messages": [
    {
      "role": "user",
      "content": "波士顿今天的天气怎么样？"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "获取指定位置的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市和州，例如 San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

常见问题

Q: 配置后前端没有显示新模型？

A: 请检查：

模型是否启用（isEnabled = true）
供应商是否启用（isEnabled = true）
清除浏览器缓存和 Cookie
硬刷新页面（Ctrl+Shift+R / Cmd+Shift+R）

Q: 模型请求失败，返回 503 错误？

A: 可能原因：

API Key 无效或过期
Base URL 配置错误
供应商服务不可用
网络连接问题

调试步骤：

检查服务器日志：pm2 logs ai-chatbot

使用 curl 测试 API：

curl -X POST <baseUrl>/chat/completions \
  -H "Authorization: Bearer <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model>","messages":[{"role":"user","content":"test"}]}'

Q: 阿里云模型和 OpenAI 模型有什么区别？

API 格式： 完全相同（OpenAI 兼容）
模型 ID： 不同（qwen-plus vs gpt-4）
Base URL： 不同（dashscope.aliyuncs.com vs api.openai.com）
功能支持： 基本相同，部分高级功能可能有差异

Q: 如何配置本地部署的模型？

A: 选择 custom 类型，配置：

{
  "type": "custom",
  "baseUrl": "http://localhost:8000/v1",
  "apiKey": "your-local-key"
}

确保本地服务提供 OpenAI 兼容的 API 接口。

技术实现说明

代码位置

动态 Provider： lib/ai/dynamic-provider.ts
数据库 Schema： lib/db/schema.ts
API 路由： app/api/admin/ai-providers/route.ts、app/api/admin/ai-models/route.ts
前端组件： components/model-selector.tsx、components/multimodal-input.tsx

Provider 创建逻辑

function getOrCreateProvider(provider: AiProvider) {
  switch (provider.type) {
    case "alibaba":
      return createOpenAI({
        apiKey: provider.apiKey,
        baseURL: provider.baseUrl, // https://dashscope.aliyuncs.com/compatible-mode/v1
      });
    
    case "openai":
      return createOpenAI({
        apiKey: provider.apiKey,
        baseURL: provider.baseUrl || "https://api.openai.com/v1",
      });
    
    case "custom":
    default:
      return createOpenAI({
        apiKey: provider.apiKey,
        baseURL: provider.baseUrl, // 任何 OpenAI 兼容的 URL
      });
  }
}

缓存机制

系统使用 Map 缓存已创建的 provider 实例，避免重复创建：

const providerCache = new Map<string, ReturnType<typeof createOpenAI>>();

缓存键格式：${providerId}-${baseUrl}

最佳实践

分类管理： 为不同用途的模型创建不同的供应商配置（如"快速对话"、"深度思考"）
设置默认： 为最常用的模型设置 isDefault = true
排序优化： 使用 sortOrder 控制前端显示顺序
描述清晰： 为每个模型添加清晰的描述，帮助用户选择
定期更新： 供应商可能推出新模型，及时更新配置
监控使用： 查看日志了解各模型的使用情况和错误率

安全建议

API Key 保护：
- 不要在前端代码中暴露 API Key
- API Key 存储在数据库中（建议加密）
- 定期轮换 API Key
访问控制：
- 只有管理员可以配置供应商和模型
- 使用 requireAdmin() 中间件保护 API 端点
费用控制：
- 设置合理的 max_tokens 限制
- 监控 API 使用量
- 考虑实现用户级别的配额限制

更新日志

2025-12-05： 实现多供应商独立配置，支持阿里云、OpenAI、OpenAI兼容
未来计划： 支持更多供应商类型（Claude、Gemini等）

9.9 KiB Raw Blame History Unescape Escape

AI 供应商配置指南

概述

支持的供应商类型

1. 阿里云 (alibaba)

2. OpenAI 官方 (openai)

3. OpenAI 兼容 (custom)

系统设置配置步骤

1. 添加 AI 供应商

2. 添加 AI 模型

3. 测试配置

API 请求格式详解

基本请求结构

多模态输入（支持的模型）

Function Calling

常见问题

Q: 配置后前端没有显示新模型？

Q: 模型请求失败，返回 503 错误？

Q: 阿里云模型和 OpenAI 模型有什么区别？

Q: 如何配置本地部署的模型？

技术实现说明

代码位置

Provider 创建逻辑

缓存机制

最佳实践

安全建议

更新日志

9.9 KiB

Raw Blame History