catalog/repos/0xsero--vllm-studio.md

# vLLM推理模型管理

`vLLM` `SGLang` `模型推理` `LLM` `推理服务器`

# vLLM Studio

面向 vLLM 和 SGLang 推理服务器的模型生命周期管理工具。

## 功能概述

- **启动/卸载模型** — 支持 vLLM 或 SGLang 后端
- **保存配方** — 可复用的模型配置，支持完整参数设置
- **推理支持** — 自动检测 GLM（`glm45`）、INTELLECT-3（`deepseek_r1`）和 MiniMax（`minimax_m2_append_think`）解析器
- **工具调用** — 原生函数调用，支持自动工具选择（GLM 和 INTELLECT-3 模型自动检测）
- **Web 界面** — 用于聊天、模型管理和使用分析
- **LiteLLM 集成** — 提供 API 网关功能（可选）

## 架构

```
┌──────────┐      ┌────────────┐      ┌─────────────┐
│  客户端  │─────▶│  控制器    │─────▶│ vLLM/SGLang │
│          │      │   :8080    │      │    :8000    │
└──────────┘      └────────────┘      └─────────────┘
                        │
                  ┌─────┴─────┐
                  │  Web 界面 │
                  │   :3000   │
                  └───────────┘
```

**可选：** 添加 LiteLLM 作为 API 网关，支持 OpenAI/Anthropic 格式转换、费用追踪和请求路由。

## 快速开始

```bash
# 安装控制器
pip install -e .

# 启动控制器
vllm-studio

# （可选）启动前端
cd frontend && npm install && npm run dev
```

## API 参考

### 健康检查与状态

| 端点 | 方法 | 描述 |
|------|------|------|
| `/health` | GET | 健康检查及后端状态 |
| `/status` | GET | 运行中的进程详情 |
| `/gpus` | GET | GPU 信息（显存、利用率） |

### 配方管理

| 端点 | 方法 | 描述 |
|------|------|------|
| `/recipes` | GET | 列出所有配方 |
| `/recipes` | POST | 创建配方 |
| `/recipes/{id}` | GET | 获取配方 |
| `/recipes/{id}` | PUT | 更新配方 |
| `/recipes/{id}` | DELETE | 删除配方 |

### 模型生命周期

| 端点 | 方法 | 描述 |
|------|------|------|
| `/launch/{recipe_id}` | POST | 从配方启动模型 |
| `/evict` | POST | 停止运行中的模型 |
| `/wait-ready` | GET | 等待后端就绪 |

### 聊天会话

| 端点 | 方法 | 描述 |
|------|------|------|
| `/chats` | GET | 列出会话 |
| `/chats` | POST | 创建会话 |
| `/chats/{id}` | GET | 获取会话及消息 |
| `/chats/{id}` | PUT | 更新会话 |
| `/chats/{id}` | DELETE | 删除会话 |
| `/chats/{id}/messages` | POST | 添加消息 |
| `/chats/{id}/fork` | POST | 派生会话 |

### MCP（模型上下文协议）

| 端点 | 方法 | 描述 |
|------|------|------|
| `/mcp/servers` | GET | 列出 MCP 服务器 |
| `/mcp/servers` | POST | 添加服务器 |
| `/mcp/tools` | GET | 列出可用工具 |
| `/mcp/tools/{server}/{tool}` | POST | 调用工具 |

## 配置

### 环境变量

```bash
VLLM_STUDIO_PORT=8080           # 控制器端口
VLLM_STUDIO_INFERENCE_PORT=8000 # vLLM/SGLang 端口
VLLM_STUDIO_API_KEY=your-key    # 可选认证密钥
```

### 配方示例

```json
{
  "id": "llama3-8b",
  "name": "Llama 3 8B",
  "model_path": "/models/Meta-Llama-3-8B-Instruct",
  "backend": "vllm",
  "tensor_parallel_size": 1,
  "max_model_len": 8192,
  "gpu_memory_utilization": 0.9,
  "trust_remote_code": true
}
```

### 配方字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `id` | string | 唯一标识符 |
| `name` | string | 显示名称 |
| `model_path` | string | 模型权重路径 |
| `backend` | string | `vllm` 或 `sglang` |
| `tensor_parallel_size` | int | GPU 张量并行数 |
| `pipeline_parallel_size` | int | 流水线并行数 |
| `max_model_len` | int | 最大上下文长度 |
| `gpu_memory_utilization` | float | 显存占用率（0-1） |
| `kv_cache_dtype` | string | KV 缓存类型 |
| `quantization` | string | 量化方式 |
| `dtype` | string | 模型数据类型 |
| `served_model_name` | string | API 暴露的模型名称 |
| `tool_call_parser` | string | 工具调用解析器 |
| `reasoning_parser` | string | 推理/思考解析器（GLM、MiniMax 自动检测） |
| `enable_auto_tool_choice` | bool | 启用自动工具选择 |
| `trust_remote_code` | bool | 允许远程代码 |
| `extra_args` | object | 额外 CLI 参数 |

## 目录结构

```
vllm-studio/
├── controller/
│   ├── app.py         # FastAPI 端点
│   ├── process.py     # 进程管理
│   ├── backends.py    # vLLM/SGLang 命令构建器
│   ├── models.py      # Pydantic 数据模型
│   ├── store.py       # SQLite 存储
│   ├── config.py      # 配置项
│   └── cli.py         # 入口点
├── frontend/          # Next.js Web 界面
├── config/
│   └── litellm.yaml   # LiteLLM 配置（可选）
└── docker-compose.yml
```

## 与 LiteLLM 配合使用（可选）

如需兼容 OpenAI/Anthropic API 格式：

```bash
docker compose up litellm
```

然后将 `http://localhost:4100` 作为 API 端点，可与任意 OpenAI 兼容客户端配合使用。

## 许可证

Apache 2.0