# 本地千问模型集成到 AI Chatbot 系统指南

## ✅ **已完成的工作**

### 1. **创建调用文档**
- 📄 文件：`千问本地模型API调用文档.md`
- 详细说明了千问 API 的所有端点和调用方式

### 2. **数据库 Schema 更新**
- ✅ 在 `lib/db/schema.ts` 中添加了 `"local"` 提供商类型
- 支持类型：`alibaba`、`openai`、`custom`、`local`

### 3. **创建本地模型 Provider**
- 📄 文件：`lib/ai/providers/local-qwen.ts`
- 实现了千问本地模型的独立调用方式
- 支持纯文本对话和图像理解
- 模拟流式响应效果

### 4. **集成到动态 Provider 系统**
- ✅ 更新 `lib/ai/dynamic-provider.ts`
- 添加了 `case "local"` 处理逻辑
- 自动根据提供商类型选择调用方式

### 5. **系统设置界面更新**
- ✅ 更新 `app/(admin)/settings/admin-settings-client.tsx`
- 添加"本地模型"选项到提供商类型下拉菜单

---

## 🚀 **配置步骤**

### **步骤 1: 登录管理后台**
访问：`http://156.225.27.52:5245/settings`

### **步骤 2: 添加本地模型提供商**

1. 切换到 **"AI 提供商"** 标签
2. 点击 **"添加 AI 提供商"**
3. 填写信息：

```
提供商名称: 千问本地模型
提供商类型: 本地模型
Base URL: http://localhost:8001
API Key: qwen25_vl_api_key_2024
是否启用: ✅
```

4. 点击 **"添加"**

### **步骤 3: 添加模型**

1. 切换到 **"AI 模型"** 标签
2. 点击 **"添加 AI 模型"**
3. 填写信息：

```
所属提供商: 千问本地模型
模型 ID: Qwen2.5-VL-3B-Instruct
显示名称: 千问2.5视觉语言模型
描述: 本地部署的千问2.5-VL-3B多模态模型，支持图像理解
支持视觉: ✅
支持图像生成: ❌
是否启用: ✅
设为默认: （可选）
排序: 0
```

4. 点击 **"添加"**

---

## 🧪 **测试步骤**

### **1. 在聊天界面测试**
1. 刷新页面
2. 点击模型选择器
3. 应该能看到 **"千问2.5视觉语言模型"**
4. 选择该模型
5. 发送一条消息测试

### **2. 测试图像理解**
1. 选择千问模型
2. 点击附件按钮上传图片
3. 输入问题："这张图片中有什么？"
4. 发送消息
5. 模型应该返回图片描述

---

## 📊 **API 调用流程**

```
用户发送消息
  ↓
Chat Component
  ↓
/api/chat
  ↓
getDynamicModel(modelId)
  ↓
getAiProviderById(providerId)
  ↓
检测 provider.type === "local"
  ↓
createLocalQwen({ baseURL, apiKey })
  ↓
POST http://localhost:8001/chat/text
  Headers: X-API-Key: qwen25_vl_api_key_2024
  Body: { messages, max_new_tokens, temperature, ... }
  ↓
千问本地 API 处理
  ↓
返回响应
  ↓
模拟流式输出到前端
```

---

## 🔧 **API 端点对应**

| 功能 | 千问 API 端点 | HTTP 方法 |
|------|--------------|-----------|
| 纯文本对话 | `/chat/text` | POST |
| 图像+文本对话 | `/chat/image` | POST |
| 图像文件对话 | `/chat/image/file` | POST |
| 健康检查 | `/health` | GET |

---

## 🎯 **特点**

### **独立调用方式**
- ✅ 不使用 OpenAI 兼容接口
- ✅ 直接调用千问原生 API
- ✅ 支持千问特有的消息格式

### **支持的功能**
- ✅ 纯文本对话
- ✅ 图像理解（多模态）
- ✅ 可配置参数（温度、max_tokens 等）
- ✅ 模拟流式响应
- ✅ 自动清理 GPU 内存

### **性能优化**
- ✅ 请求超时控制（默认 30 秒）
- ✅ 错误处理和重试
- ✅ Provider 实例缓存

---

## 📝 **配置参数说明**

### **千问 API 参数**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `max_new_tokens` | int | 512 | 最大生成 token 数 |
| `temperature` | float | 0.7 | 控制随机性（0-1） |
| `top_p` | float | 0.9 | 核采样参数 |
| `do_sample` | bool | true | 是否使用采样 |

### **Provider 配置**

```typescript
{
  name: "千问本地模型",
  type: "local",
  baseUrl: "http://localhost:8001",
  apiKey: "qwen25_vl_api_key_2024",
  isEnabled: true
}
```

---

## 🚨 **注意事项**

1. **网络访问**：确保 AI Chatbot 服务器可以访问 `localhost:8001`
2. **API 密钥**：必须在请求头中包含正确的 API 密钥
3. **超时设置**：大图片处理可能需要更长时间
4. **GPU 内存**：模型会自动清理 GPU 内存，但并发请求仍需注意
5. **流式响应**：当前实现是模拟流式，非真实流式

---

## 🔍 **故障排除**

### **问题 1：模型不显示**
- 检查提供商是否启用
- 检查模型是否启用
- 刷新页面清除缓存

### **问题 2：请求失败**
- 检查千问 API 服务是否运行：`curl http://localhost:8001/health`
- 检查 API 密钥是否正确
- 查看服务器日志：`pm2 logs ai-chatbot`

### **问题 3：响应慢**
- 检查 GPU 内存使用情况
- 调整 `max_new_tokens` 参数
- 限制并发请求数量

---

## 📚 **相关文档**

- 千问 API 完整文档：`千问本地模型API调用文档.md`
- Provider 代码：`lib/ai/providers/local-qwen.ts`
- Dynamic Provider：`lib/ai/dynamic-provider.ts`
- 系统设置：`app/(admin)/settings/admin-settings-client.tsx`

---

## 🎉 **完成！**

本地千问模型已成功集成到 AI Chatbot 系统中，作为独立的提供商类型，享有完全独立的调用方式！

**下一步**：
1. 部署代码到服务器
2. 在系统设置中配置千问提供商和模型
3. 测试聊天和图像理解功能

---

**文档版本**: 1.0.0  
**创建日期**: 2025-12-05  
**作者**: AI Assistant