# VLLM_API

**Repository Path**: thunderlz/vllm_api

## Basic Information

- **Project Name**: VLLM_API
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-12
- **Last Updated**: 2025-12-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vLLM API 服务封装

本项目使用vLLM将Qwen系列模型封装为OpenAI兼容的API服务。

## 支持的模型

1. **Qwen3-8B** - 纯文本生成模型
   - 路径: `/Users/leizhen/.cache/modelscope/hub/models/Qwen/Qwen3-8B`
   - 端口: 8010
   - 特点: 支持思考模式（thinking mode），32K上下文

2. **Qwen3-VL-8B-Instruct** - 视觉语言模型
   - 路径: `/Users/leizhen/.cache/modelscope/hub/models/Qwen/Qwen3-VL-8B-Instruct`
   - 端口: 8011
   - 特点: 支持图像理解，多模态能力
   - 注意: 需要更大的上下文长度（8192 tokens）以处理多模态输入

## 项目结构

```
vllm_api/
├── start_text_api.sh      # 文本模型启动脚本
├── start_vision_api.sh    # 视觉模型启动脚本
├── manage_apis.py         # 服务管理脚本
├── test_apis.py          # API测试脚本
└── README.md             # 本文档
```

## 环境要求

- Conda环境: `vllm` (已安装vllm 0.10.2)
- Python: 3.13.7
- 模型文件: 已下载到本地缓存目录

## 快速开始

### 1. 启动所有服务

```bash
# 给脚本添加执行权限
chmod +x start_text_api.sh start_vision_api.sh

# 使用管理脚本启动所有服务
python manage_apis.py start all
```

### 2. 单独启动服务

```bash
# 启动文本模型服务
python manage_apis.py start text

# 启动视觉模型服务  
python manage_apis.py start vision
```

### 3. 查看服务状态

```bash
python manage_apis.py status
```

### 4. 停止服务

```bash
# 停止所有服务
python manage_apis.py stop all

# 停止指定服务
python manage_apis.py stop text
python manage_apis.py stop vision
```

## API端点

### 文本模型 (端口 8010)
- OpenAI兼容API: `http://localhost:8010/v1`
- 文档: `http://localhost:8010/docs`
- 健康检查: `http://localhost:8010/health`

### 视觉模型 (端口 8011)
- OpenAI兼容API: `http://localhost:8011/v1`
- 文档: `http://localhost:8011/docs`
- 健康检查: `http://localhost:8011/health`

## API使用示例

### 聊天补全 (Chat Completion)

```python
import requests
import json

url = "http://localhost:8010/v1/chat/completions"

headers = {
    "Content-Type": "application/json"
}

data = {
    "model": "qwen3-8b",
    "messages": [
        {"role": "system", "content": "你是一个有帮助的AI助手"},
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "max_tokens": 100,
    "temperature": 0.7
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result["choices"][0]["message"]["content"])
```

### 获取模型列表

```python
import requests

url = "http://localhost:8010/v1/models"
response = requests.get(url)
models = response.json()

for model in models["data"]:
    print(f"Model: {model['id']}")
```

## 测试API

运行完整的API测试：

```bash
python test_apis.py
```

测试特定服务：

```bash
# 测试文本模型
python test_apis.py text

# 测试视觉模型
python test_apis.py vision
```

## 手动启动（不使用管理脚本）

### 启动文本模型服务

```bash
conda activate vllm
./start_text_api.sh
```

### 启动视觉模型服务

```bash
conda activate vllm
./start_vision_api.sh
```

## 日志文件

- 文本模型日志: `text_api.log`
- 视觉模型日志: `vision_api.log`
- PID文件: `text_api.pid`, `vision_api.pid`

## 注意事项

1. **模型加载时间**: 首次启动服务时，模型加载可能需要几分钟时间，具体取决于硬件性能
2. **内存要求**: 每个8B模型大约需要16GB GPU内存（或相应CPU内存）
3. **端口冲突**: 确保8010和8011端口未被其他应用占用
4. **视觉模型**: Qwen3-VL-8B-Instruct支持图像输入，请参考Qwen-VL文档使用多模态API
5. **API参数限制**: 
   - 最大上下文长度: 4096 tokens
   - 请求中的 `max_tokens` 参数必须满足：`输入token数 + max_tokens ≤ 4096`
   - 默认生成参数: temperature=0.7, top_p=0.9
   - 可在API请求中覆盖这些参数
6. **启动参数**: 已配置 `--max-model-len 4096` 和 `--max-num-batched-tokens 4096` 避免参数冲突

## 故障排除

### 服务无法启动
1. 检查conda环境是否正确激活
2. 检查模型路径是否存在
3. 查看日志文件获取详细错误信息

### API请求失败
1. 检查服务是否正在运行: `python manage_apis.py status`
2. 检查端口是否被占用
3. 验证API端点URL是否正确

### 内存不足
1. 减少`--max-model-len`参数值
2. 使用CPU推理（性能较慢）
3. 考虑使用量化版本模型

## 扩展功能

如需添加以下功能，可修改相应脚本：

1. **API认证**: 在启动命令中添加`--api-key`参数
2. **CORS配置**: 添加`--cors-origins`参数
3. **负载均衡**: 使用多个GPU或部署多个实例
4. **监控指标**: 启用vLLM的指标端点

## 许可证

本项目代码基于MIT许可证。模型使用请遵守Qwen模型的相应许可证。