lovart3/千问本地模型API调用文档.md

千问本地模型 API 调用文档

🚀 服务信息

• 模型名称: Qwen2.5-VL-3B-Instruct（千问2.5视觉语言模型3B）
• 服务地址: http://156.225.27.52:8001
• 本地地址: http://localhost:8001
• API 密钥: qwen25_vl_api_key_2024
• 密钥头名称: X-API-Key

---

📡 API 端点

1. 健康检查

GET /health

响应示例：

{
  "status": "healthy",
  "model_loaded": true,
  "device": "cuda",
  "model_path": "/root/qwen25_vl_deployment/qwen/Qwen2.5-VL-3B-Instruct"
}

---

2. 纯文本对话 ⭐

POST /chat/text
Headers:
  X-API-Key: qwen25_vl_api_key_2024
  Content-Type: application/json

请求体：

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "你好，请介绍一下你自己"
        }
      ]
    }
  ],
  "max_new_tokens": 512,
  "temperature": 0.7,
  "top_p": 0.9,
  "do_sample": true
}

响应示例：

{
  "response": "你好！我是千问2.5视觉语言模型...",
  "usage": {
    "tokens": 50
  },
  "processing_time": 1.23
}

---

3. 图像对话（Base64）

POST /chat/image
Headers:
  X-API-Key: qwen25_vl_api_key_2024
  Content-Type: application/json

请求体：

{
  "image_base64": "/9j/4AAQSkZJRg...(base64图片数据)",
  "message": "请描述这张图片的内容",
  "max_new_tokens": 512,
  "temperature": 0.7,
  "top_p": 0.9,
  "do_sample": true
}

响应示例：

{
  "response": "这张图片显示了...",
  "usage": {
    "tokens": 80
  },
  "processing_time": 2.45
}

---

4. 图像对话（文件上传）

POST /chat/image/file
Headers:
  X-API-Key: qwen25_vl_api_key_2024
Content-Type: multipart/form-data

表单字段：

• file: 图片文件（必填）
• message: 提问内容（默认："请描述这张图片"）
• max_new_tokens: 最大生成token数（默认：512）
• temperature: 温度参数（默认：0.7）
• top_p: Top-p采样（默认：0.9）
• do_sample: 是否采样（默认：true）

cURL 示例：

curl -X POST "http://156.225.27.52:8001/chat/image/file" \
  -H "X-API-Key: qwen25_vl_api_key_2024" \
  -F "file=@/path/to/image.jpg" \
  -F "message=这张图片中有什么？" \
  -F "max_new_tokens=512" \
  -F "temperature=0.7"

---

🔑 参数说明

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

---

🛠️ 消息格式

文本消息

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "你的问题"
    }
  ]
}

图像+文本消息

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "image": "data:image/jpeg;base64,/9j/4AAQ..."
    },
    {
      "type": "text",
      "text": "请分析这张图片"
    }
  ]
}

---

🚨 错误码

状态码	说明
200	请求成功
401	API密钥无效
500	服务器内部错误

---

📊 性能指标

• 设备: CUDA (GPU)
• 模型大小: 3B 参数
• 平均响应时间: 1-3 秒（纯文本）
• 图像处理时间: 2-5 秒
• 支持最大分辨率: 2048x2048

---

🔍 使用建议

1. 纯文本对话：使用 /chat/text 端点
2. 图像分析：使用 /chat/image/file 端点（推荐）
3. 并发限制：建议不超过 3 个并发请求
4. 超时设置：建议设置 30 秒超时

---

📦 Node.js 调用示例

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

// 纯文本对话
async function chatText(message) {
  const response = await axios.post(
    'http://156.225.27.52:8001/chat/text',
    {
      messages: [
        {
          role: 'user',
          content: [
            { type: 'text', text: message }
          ]
        }
      ],
      max_new_tokens: 512,
      temperature: 0.7
    },
    {
      headers: {
        'X-API-Key': 'qwen25_vl_api_key_2024',
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data.response;
}

// 图像对话
async function chatImage(imagePath, message) {
  const form = new FormData();
  form.append('file', fs.createReadStream(imagePath));
  form.append('message', message);
  form.append('max_new_tokens', '512');
  form.append('temperature', '0.7');
  
  const response = await axios.post(
    'http://156.225.27.52:8001/chat/image/file',
    form,
    {
      headers: {
        ...form.getHeaders(),
        'X-API-Key': 'qwen25_vl_api_key_2024'
      }
    }
  );
  return response.data.response;
}

---

✅ 测试 API

访问 Swagger UI 文档：

http://156.225.27.52:8001/docs

---

文档版本: 1.0.0
最后更新: 2025-12-05