@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/mlops/inference/vllm/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: serving-llms-vllm
+description: "vLLM：高吞吐量 LLM 服务、OpenAI API、量化。"
+version: 1.0.0
+author: Orchestra Research
+license: MIT
+dependencies: [vllm, torch, transformers]
+platforms: [linux, macos]
+metadata:
+  hermes:
+    tags: [vLLM, Inference Serving, PagedAttention, Continuous Batching, High Throughput, Production, OpenAI API, Quantization, Tensor Parallelism]
+
+---
+
+# vLLM - 高性能 LLM 服务
+
+## 何时使用
+
+适用于 deploying production LLM APIs、优化推理延迟/吞吐量，或在有限的 GPU 内存下部署模型。支持兼容 OpenAI 的 endpoints、量化（GPTQ/AWQ/FP8）以及 tensor parallelism。
+
+## 快速开始
+
+vLLM 通过 PagedAttention（基于 block 的 KV cache）和 continuous batching（混合 prefill/decode 请求）实现了比标准 transformers 高 24 倍的吞吐量。
+
+**安装**:
+```bash
+pip install vllm
+```
+
+**基础离线推理**:
+```python
+from vllm import LLM, SamplingParams
+
+llm = LLM(model="meta-llama/Llama-3-8B-Instruct")
+sampling = SamplingParams(temperature=0.7, max_tokens=256)
+
+outputs = llm.generate(["Explain quantum computing"], sampling)
+print(outputs[0].outputs[0].text)
+```
+
+**兼容 OpenAI 的服务器**:
+```bash
+vllm serve meta-llama/Llama-3-8B-Instruct
+
+# Query with OpenAI SDK
+python -c "
+from openai import OpenAI
+client = OpenAI(base_url='http://localhost:8000/v1', api_key='EMPTY')
+print(client.chat.completions.create(
+    model='meta-llama/Llama-3-8B-Instruct',
+    messages=[{'role': 'user', 'content': 'Hello!'}]
+).choices[0].message.content)
+"
+```
+
+## 常见工作流
+
+### 工作流 1：生产级 API 部署
+
+复制此清单并跟踪进度：
+
+```
+Deployment Progress:
+- [ ] Step 1: Configure server settings
+- [ ] Step 2: Test with limited traffic
+- [ ] Step 3: Enable monitoring
+- [ ] Step 4: Deploy to production
+- [ ] Step 5: Verify performance metrics
+```
+
+**第 1 步：配置服务器设置**
+
+根据您的模型大小选择配置：
+
+```bash
+# For 7B-13B models on single GPU
+vllm serve meta-llama/Llama-3-8B-Instruct \
+  --gpu-memory-utilization 0.9 \
+  --max-model-len 8192 \
+  --port 8000
+
+# For 30B-70B models with tensor parallelism
+vllm serve meta-llama/Llama-2-70b-hf \
+  --tensor-parallel-size 4 \
+  --gpu-memory-utilization 0.9 \
+  --quantization awq \
+  --port 8000
+
+# For production with caching and metrics
+vllm serve meta-llama/Llama-3-8B-Instruct \
+  --gpu-memory-utilization 0.9 \
+  --enable-prefix-caching \
+  --enable-metrics \
+  --metrics-port 9090 \
+  --port 8000 \
+  --host 0.0.0.0
+```
+
+**第 2 步：使用有限流量进行测试**
+
+在生产环境部署前进行负载测试：
+
+```bash
+# Install load testing tool
+pip install locust
+
+# Create test_load.py with sample requests
+# Run: locust -f test_load.py --host http://localhost:8000
+```
+
+验证 TTFT（time to first token）< 500ms 且吞吐量 > 100 req/sec。
+
+**第 3 步：启用监控**
+
+vLLM 在 9090 端口暴露 Prometheus 指标：
+
+```bash
+curl http://localhost:9090/metrics | grep vllm
+```
+
+需要监控的关键指标：
+- `vllm:time_to_first_token_seconds` - 延迟
+- `vllm:num_requests_running` - 活跃请求数
+- `vllm:gpu_cache_usage_perc` - KV cache 利用率
+
+**第 4 步：部署到生产环境**
+
+使用 Docker 进行一致的部署：
+
+```bash
+# Run vLLM in Docker
+docker run --gpus all -p 8000:8000 \
+  vllm/vllm-openai:latest \
+  --model meta-llama/Llama-3-8B-Instruct \
+  --gpu-memory-utilization 0.9 \
+  --enable-prefix-caching
+```
+
+**第 5 步：验证性能指标**
+
+检查部署是否达到目标：
+- TTFT < 500ms（对于短提示词）
+- 吞吐量 > 目标 req/sec
+- GPU 利用率 > 80%
+- 日志中没有 OOM 错误
+
+### 工作流 2：离线批量推理
+
+用于在不产生服务器开销的情况下处理大型数据集。
+
+复制此清单：
+
+```
+Batch Processing:
+- [ ] Step 1: Prepare input data
+- [ ] Step 2: Configure LLM engine
+- [ ] Step 3: Run batch inference
+- [ ] Step 4: Process results
+```
+
+**第 1 步：准备输入数据**
+
+```python
+# Load prompts from file
+prompts = []
+with open("prompts.txt") as f:
+    prompts = [line.strip() for line in f]
+
+print(f"Loaded {len(prompts)} prompts")
+```
+
+**第 2 步：配置 LLM 引擎**
+
+```python
+from vllm import LLM, SamplingParams
+
+llm = LLM(
+    model="meta-llama/Llama-3-8B-Instruct",
+    tensor_parallel_size=2,  # Use 2 GPUs
+    gpu_memory_utilization=0.9,
+    max_model_len=4096
+)
+
+sampling = SamplingParams(
+    temperature=0.7,
+    top_p=0.95,
+    max_tokens=512,
+    stop=["</s>", "\n\n"]
+)
+```
+
+**第 3 步：运行批量推理**
+
+vLLM 会自动对请求进行批处理以提高效率：
+
+```python
+# Process all prompts in one call
+outputs = llm.generate(prompts, sampling)
+
+# vLLM handles batching internally
+# No need to manually chunk prompts
+```
+
+**第 4 步：处理结果**
+
+```python
+# Extract generated text
+results = []
+for output in outputs:
+    prompt = output.prompt
+    generated = output.outputs[0].text
+    results.append({
+        "prompt": prompt,
+        "generated": generated,
+        "tokens": len(output.outputs[0].token_ids)
+    })
+
+# Save to file
+import json
+with open("results.jsonl", "w") as f:
+    for result in results:
+        f.write(json.dumps(result) + "\n")
+
+print(f"Processed {len(results)} prompts")
+```
+
+### 工作流 3：量化模型服务
+
+在有限的 GPU 内存中容纳大型模型。
+
+```
+Quantization Setup:
+- [ ] Step 1: Choose quantization method
+- [ ] Step 2: Find or create quantized model
+- [ ] Step 3: Launch with quantization flag
+- [ ] Step 4: Verify accuracy
+```
+
+**第 1 步：选择量化方法**
+
+- **AWQ**：最适合 70B 模型，精度损失极小
+- **GPTQ**：支持广泛的模型，压缩效果好
+- **FP8**：在 H100 GPU 上速度最快
+
+**第 2 步：寻找或创建量化模型**
+
+使用 HuggingFace 上的预量化模型：
+
+```bash
+# Search for AWQ models
+# Example: TheBloke/Llama-2-70B-AWQ
+```
+
+**第 3 步：使用量化标志启动**
+
+```bash
+# Using pre-quantized model
+vllm serve TheBloke/Llama-2-70B-AWQ \
+  --quantization awq \
+  --tensor-parallel-size 1 \
+  --gpu-memory-utilization 0.95
+
+# Results: 70B model in ~40GB VRAM
+```
+
+**第 4 步：验证准确性**
+
+测试输出以确保符合预期的质量：
+
+```python
+# Compare quantized vs non-quantized responses
+# Verify task-specific performance unchanged
+```
+
+## 何时使用及替代方案
+
+**以下情况请使用 vLLM：**
+- 部署生产级 LLM API（100+ req/sec）
+- 提供兼容 OpenAI 的 endpoints
+- GPU 内存有限，但需要运行大型模型
+- 多用户应用（聊天机器人、助手）
+- 需要在高吞吐量下实现低延迟
+
+**以下情况请使用替代方案：**
+- **llama.cpp**：CPU/边缘推理，单用户
+- **HuggingFace transformers**：研究、原型设计、一次性生成
+- **TensorRT-LLM**：仅限 NVIDIA，需要极致的最大性能
+- **Text-Generation-Inference**：已在 HuggingFace 生态系统中
+
+## 常见问题
+
+**问题：模型加载期间出现内存不足 (Out of memory)**
+
+减少内存使用量：
+```bash
+vllm serve MODEL \
+  --gpu-memory-utilization 0.7 \
+  --max-model-len 4096
+```
+
+或使用量化：
+```bash
+vllm serve MODEL --quantization awq
+```
+
+**问题：第一个 token 生成缓慢（TTFT > 1 秒）**
+
+对于重复的提示词，启用 prefix caching：
+```bash
+vllm serve MODEL --enable-prefix-caching
+```
+
+对于长提示词，启用 chunked prefill：
+```bash
+vllm serve MODEL --enable-chunked-prefill
+```
+
+**问题：找不到模型错误**
+
+对于自定义模型，使用 `--trust-remote-code`：
+```bash
+vllm serve MODEL --trust-remote-code
+```
+
+**问题：吞吐量低（<50 req/sec）**
+
+增加并发序列数：
+```bash
+vllm serve MODEL --max-num-seqs 512
+```
+
+使用 `nvidia-smi` 检查 GPU 利用率 - 应大于 80%。
+
+**问题：推理速度低于预期**
+
+验证 tensor parallelism 是否使用了 2 的幂次方个 GPU：
+```bash
+vllm serve MODEL --tensor-parallel-size 4  # Not 3
+```
+
+启用 speculative decoding 以加快生成速度：
+```bash
+vllm serve MODEL --speculative-model DRAFT_MODEL
+```
+
+## 进阶主题
+
+**服务器部署模式**：有关 Docker、Kubernetes 和负载均衡配置，请参见 [references/server-deployment.md](references/server-deployment.md)。
+
+**性能优化**：有关 PagedAttention 调优、continuous batching 的详细信息以及基准测试结果，请参见 [references/optimization.md](references/optimization.md)。
+
+**量化指南**：有关 AWQ/GPTQ/FP8 设置、模型准备和准确性比较，请参见 [references/quantization.md](references/quantization.md)。
+
+**故障排查**: 有关详细的错误信息、调试步骤和性能诊断，请参见 [references/troubleshooting.md](references/troubleshooting.md)。
+
+## 硬件要求
+
+- **小型模型 (7B-13B)**：1x A10 (24GB) 或 A100 (40GB)
+- **中型模型 (30B-40B)**：使用 tensor parallelism 的 2x A100 (40GB)
+- **大型模型 (70B+)**：4x A100 (40GB) 或 2x A100 (80GB)，使用 AWQ/GPTQ
+
+支持 platforms: NVIDIA (主要)、AMD ROCm、Intel GPUs、TPUs
+
+## 资源
+
+- 官方文档：https://docs.vllm.ai
+- GitHub：https://github.com/vllm-project/vllm
+- 论文："Efficient Memory Management for Large Language Model Serving with PagedAttention" (SOSP 2023)
+- 社区: https://discuss.vllm.ai

package/extensions/skills/builtin/mlops/inference/vllm/references/optimization.md

@@ -0,0 +1,226 @@
+# Performance Optimization
+
+## 目录
+- PagedAttention 详解
+- Continuous batching 机制
+- Prefix caching 策略
+- Speculative decoding 设置
+- 基准测试结果与对比
+- 性能调优指南
+
+## PagedAttention 详解
+
+**传统 attention 的问题**:
+- KV cache 存储在连续的内存中
+- 由于内存碎片化浪费了约 50% 的 GPU 显存
+- 无法针对不同的序列长度进行动态重新分配
+
+**PagedAttention 解决方案**:
+- 将 KV cache 划分为固定大小的 block（类似于操作系统的虚拟内存）
+- 从空闲 block 队列中进行动态分配
+- 跨序列共享 block（用于 prefix caching）
+
+**节省内存示例**:
+```
+Traditional: 70B model needs 160GB KV cache → OOM on 8x A100
+PagedAttention: 70B model needs 80GB KV cache → Fits on 4x A100
+```
+
+**配置**:
+```bash
+# Block size (default: 16 tokens)
+vllm serve MODEL --block-size 16
+
+# Number of GPU blocks (auto-calculated)
+# Controlled by --gpu-memory-utilization
+vllm serve MODEL --gpu-memory-utilization 0.9
+```
+
+## Continuous batching 机制
+
+**传统 batching**:
+- 等待 batch 中的所有序列完成生成
+- 在等待最长序列完成时，GPU 处于空闲状态
+- GPU 利用率低（约 40-60%）
+
+**Continuous batching**:
+- 当有处理槽位空闲时加入新的请求
+- 在同一个 batch 中混合 prefill（新请求）和 decode（进行中的请求）
+- GPU 利用率高（>90%）
+
+**吞吐量提升**:
+```
+Traditional batching: 50 req/sec @ 50% GPU util
+Continuous batching: 200 req/sec @ 90% GPU util
+= 4x throughput improvement
+```
+
+**调优参数**:
+```bash
+# Max concurrent sequences (higher = more batching)
+vllm serve MODEL --max-num-seqs 256
+
+# Prefill/decode schedule (auto-balanced by default)
+# No manual tuning needed
+```
+
+## Prefix caching 策略
+
+为常见的提示词前缀复用已计算出的 KV cache。
+
+**用例**:
+- 跨请求重复的 System prompts
+- 每个提示词中包含的 Few-shot 示例
+- 具有重叠文本块的 RAG 上下文
+
+**节省效果示例**:
+```
+Prompt: [System: 500 tokens] + [User: 100 tokens]
+
+Without caching: Compute 600 tokens every request
+With caching: Compute 500 tokens once, then 100 tokens/request
+= 83% faster TTFT
+```
+
+**启用 prefix caching**:
+```bash
+vllm serve MODEL --enable-prefix-caching
+```
+
+**自动前缀检测**:
+- vLLM 会自动检测公共前缀
+- 无需修改代码
+- 兼容 OpenAI 兼容 API
+
+**缓存命中率监控**:
+```bash
+curl http://localhost:9090/metrics | grep cache_hit
+# vllm_cache_hit_rate: 0.75  (75% hit rate)
+```
+
+## Speculative decoding 设置
+
+使用较小的“draft”模型来提议 token，并由较大的模型进行验证。
+
+**速度提升**:
+```
+Standard: Generate 1 token per forward pass
+Speculative: Generate 3-5 tokens per forward pass
+= 2-3x faster generation
+```
+
+**工作原理**:
+1. Draft 模型提议 K 个 token（速度快）
+2. Target 模型并行验证所有 K 个 token（单次运行）
+3. 接受验证通过的 token，从第一个被拒绝的 token 处重新开始
+
+**使用独立 draft 模型进行设置**:
+```bash
+vllm serve meta-llama/Llama-3-70B-Instruct \
+  --speculative-model TinyLlama/TinyLlama-1.1B-Chat-v1.0 \
+  --num-speculative-tokens 5
+```
+
+**使用 n-gram draft 进行设置**（无需独立模型）:
+```bash
+vllm serve MODEL \
+  --speculative-method ngram \
+  --num-speculative-tokens 3
+```
+
+**适用场景**:
+- 输出长度 > 100 个 token
+- Draft 模型比 target 模型小 5-10 倍
+- 可以接受 2-3% 的精度折损
+
+## 基准测试结果
+
+**vLLM 与 HuggingFace Transformers 对比**（Llama 3 8B, A100）:
+```
+Metric                  | HF Transformers | vLLM   | Improvement
+------------------------|-----------------|--------|------------
+Throughput (req/sec)    | 12              | 280    | 23x
+TTFT (ms)              | 850             | 120    | 7x
+Tokens/sec             | 45              | 2,100  | 47x
+GPU Memory (GB)        | 28              | 16     | 1.75x less
+```
+
+**vLLM 与 TensorRT-LLM 对比**（Llama 2 70B, 4x A100）:
+```
+Metric                  | TensorRT-LLM | vLLM   | Notes
+------------------------|--------------|--------|------------------
+Throughput (req/sec)    | 320          | 285    | TRT 12% faster
+Setup complexity        | High         | Low    | vLLM much easier
+NVIDIA-only            | Yes          | No     | vLLM multi-platform
+Quantization support    | FP8, INT8    | AWQ/GPTQ/FP8 | vLLM more options
+```
+
+## 性能调优指南
+
+**第 1 步：测量基准性能**
+
+```bash
+# Install benchmarking tool
+pip install locust
+
+# Run baseline benchmark
+vllm bench throughput \
+  --model MODEL \
+  --input-tokens 128 \
+  --output-tokens 256 \
+  --num-prompts 1000
+
+# Record: throughput, TTFT, tokens/sec
+```
+
+**第 2 步：调整显存利用率**
+
+```bash
+# Try different values: 0.7, 0.85, 0.9, 0.95
+vllm serve MODEL --gpu-memory-utilization 0.9
+```
+
+数值越高 = batch 容量越大 = 吞吐量越高，但有 OOM 的风险。
+
+**第 3 步：调整并发数**
+
+```bash
+# Try values: 128, 256, 512, 1024
+vllm serve MODEL --max-num-seqs 256
+```
+
+数值越高 = batching 的机会越多，但可能会增加延迟。
+
+**第 4 步：启用优化选项**
+
+```bash
+vllm serve MODEL \
+  --enable-prefix-caching \     # For repeated prompts
+  --enable-chunked-prefill \    # For long prompts
+  --gpu-memory-utilization 0.9 \
+  --max-num-seqs 512
+```
+
+**第 5 步：重新进行基准测试并对比**
+
+预期提升目标:
+- 吞吐量 (Throughput): +30-100%
+- 首字延迟 (TTFT): -20-50%
+- GPU 利用率 (GPU utilization): >85%
+
+**常见性能问题**:
+
+**低吞吐量 (<50 req/sec)**:
+- 增大 `--max-num-seqs`
+- 启用 `--enable-prefix-caching`
+- 检查 GPU 利用率（应大于 80%）
+
+**高首字延迟 TTFT (>1 秒)**:
+- 启用 `--enable-chunked-prefill`
+- 尽可能减小 `--max-model-len`
+- 检查模型是否对于 GPU 而言过大
+
+**OOM 错误**:
+- 将 `--gpu-memory-utilization` 降低至 0.7
+- 减小 `--max-model-len`
+- 使用量化（如 `--quantization awq`）