# 千问本地模型 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. **健康检查**
```http
GET /health
```

**响应示例：**
```json
{
  "status": "healthy",
  "model_loaded": true,
  "device": "cuda",
  "model_path": "/root/qwen25_vl_deployment/qwen/Qwen2.5-VL-3B-Instruct"
}
```

---

### 2. **纯文本对话** ⭐
```http
POST /chat/text
Headers:
  X-API-Key: qwen25_vl_api_key_2024
  Content-Type: application/json
```

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

**响应示例：**
```json
{
  "response": "你好！我是千问2.5视觉语言模型...",
  "usage": {
    "tokens": 50
  },
  "processing_time": 1.23
}
```

---

### 3. **图像对话（Base64）**
```http
POST /chat/image
Headers:
  X-API-Key: qwen25_vl_api_key_2024
  Content-Type: application/json
```

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

**响应示例：**
```json
{
  "response": "这张图片显示了...",
  "usage": {
    "tokens": 80
  },
  "processing_time": 2.45
}
```

---

### 4. **图像对话（文件上传）**
```http
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 示例：**
```bash
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 | 是否使用采样策略 |

---

## 🛠️ **消息格式**

### **文本消息**
```json
{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "你的问题"
    }
  ]
}
```

### **图像+文本消息**
```json
{
  "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 调用示例**

```javascript
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