lovart3/本地千问模型集成指南.md

本地千问模型集成到 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 配置

{
  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