Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-evaluation-evaluating-llms-harness.md

@@ -0,0 +1,512 @@
+---
+title: "Evaluating Llms Harness — lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc"
+sidebar_label: "Evaluating Llms Harness"
+description: "lm-eval-harness：对 LLM 进行基准测试（MMLU、GSM8K 等）"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Evaluating Llms Harness
+
+lm-eval-harness：对 LLM 进行基准测试（MMLU、GSM8K 等）。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/mlops/evaluation/evaluating-llms-harness` |
+| 版本 | `1.0.0` |
+| 作者 | Orchestra Research |
+| 许可证 | MIT |
+| 依赖项 | `lm-eval`, `transformers`, `vllm` |
+| 平台 | linux, macos |
+| 标签 | `Evaluation`, `LM Evaluation Harness`, `Benchmarking`, `MMLU`, `HumanEval`, `GSM8K`, `EleutherAI`, `Model Quality`, `Academic Benchmarks`, `Industry Standard` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# lm-evaluation-harness - LLM 基准测试
+
+## 内容概览
+
+在 60+ 个学术基准（MMLU、HumanEval、GSM8K、TruthfulQA、HellaSwag）上评估 LLM。适用于基准测试模型质量、比较模型、报告学术结果或跟踪训练进度。行业标准工具，被 EleutherAI、HuggingFace 及各大实验室广泛使用。支持 HuggingFace、vLLM 及 API。
+
+## 快速开始
+
+lm-evaluation-harness 使用标准化 prompt（提示词）和指标，在 60+ 个学术基准上评估 LLM。
+
+**安装**：
+```bash
+pip install lm-eval
+```
+
+**评估任意 HuggingFace 模型**：
+```bash
+lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf \
+  --tasks mmlu,gsm8k,hellaswag \
+  --device cuda:0 \
+  --batch_size 8
+```
+
+**查看可用任务**：
+```bash
+lm_eval --tasks list
+```
+
+## 常用工作流
+
+### 工作流 1：标准基准评估
+
+在核心基准（MMLU、GSM8K、HumanEval）上评估模型。
+
+复制此检查清单：
+
+```
+基准评估：
+- [ ] 步骤 1：选择基准套件
+- [ ] 步骤 2：配置模型
+- [ ] 步骤 3：运行评估
+- [ ] 步骤 4：分析结果
+```
+
+**步骤 1：选择基准套件**
+
+**核心推理基准**：
+- **MMLU**（Massive Multitask Language Understanding）- 57 个科目，多项选择
+- **GSM8K** - 小学数学应用题
+- **HellaSwag** - 常识推理
+- **TruthfulQA** - 真实性与事实性
+- **ARC**（AI2 Reasoning Challenge）- 科学题目
+
+**代码基准**：
+- **HumanEval** - Python 代码生成（164 道题）
+- **MBPP**（Mostly Basic Python Problems）- Python 编程
+
+**标准套件**（推荐用于模型发布）：
+```bash
+--tasks mmlu,gsm8k,hellaswag,truthfulqa,arc_challenge
+```
+
+**步骤 2：配置模型**
+
+**HuggingFace 模型**：
+```bash
+lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf,dtype=bfloat16 \
+  --tasks mmlu \
+  --device cuda:0 \
+  --batch_size auto  # Auto-detect optimal batch size
+```
+
+**量化模型（4-bit/8-bit）**：
+```bash
+lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf,load_in_4bit=True \
+  --tasks mmlu \
+  --device cuda:0
+```
+
+**自定义 checkpoint**：
+```bash
+lm_eval --model hf \
+  --model_args pretrained=/path/to/my-model,tokenizer=/path/to/tokenizer \
+  --tasks mmlu \
+  --device cuda:0
+```
+
+**步骤 3：运行评估**
+
+```bash
+# Full MMLU evaluation (57 subjects)
+lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf \
+  --tasks mmlu \
+  --num_fewshot 5 \  # 5-shot evaluation (standard)
+  --batch_size 8 \
+  --output_path results/ \
+  --log_samples  # Save individual predictions
+
+# Multiple benchmarks at once
+lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf \
+  --tasks mmlu,gsm8k,hellaswag,truthfulqa,arc_challenge \
+  --num_fewshot 5 \
+  --batch_size 8 \
+  --output_path results/llama2-7b-eval.json
+```
+
+**步骤 4：分析结果**
+
+结果保存至 `results/llama2-7b-eval.json`：
+
+```json
+{
+  "results": {
+    "mmlu": {
+      "acc": 0.459,
+      "acc_stderr": 0.004
+    },
+    "gsm8k": {
+      "exact_match": 0.142,
+      "exact_match_stderr": 0.006
+    },
+    "hellaswag": {
+      "acc_norm": 0.765,
+      "acc_norm_stderr": 0.004
+    }
+  },
+  "config": {
+    "model": "hf",
+    "model_args": "pretrained=meta-llama/Llama-2-7b-hf",
+    "num_fewshot": 5
+  }
+}
+```
+
+### 工作流 2：跟踪训练进度
+
+在训练过程中评估 checkpoint。
+
+```
+训练进度跟踪：
+- [ ] 步骤 1：设置定期评估
+- [ ] 步骤 2：选择快速基准
+- [ ] 步骤 3：自动化评估
+- [ ] 步骤 4：绘制学习曲线
+```
+
+**步骤 1：设置定期评估**
+
+每 N 个训练步骤评估一次：
+
+```bash
+#!/bin/bash
+# eval_checkpoint.sh
+
+CHECKPOINT_DIR=$1
+STEP=$2
+
+lm_eval --model hf \
+  --model_args pretrained=$CHECKPOINT_DIR/checkpoint-$STEP \
+  --tasks gsm8k,hellaswag \
+  --num_fewshot 0 \  # 0-shot for speed
+  --batch_size 16 \
+  --output_path results/step-$STEP.json
+```
+
+**步骤 2：选择快速基准**
+
+适合频繁评估的快速基准：
+- **HellaSwag**：单 GPU 约 10 分钟
+- **GSM8K**：约 5 分钟
+- **PIQA**：约 2 分钟
+
+不适合频繁评估（耗时过长）：
+- **MMLU**：约 2 小时（57 个科目）
+- **HumanEval**：需要执行代码
+
+**步骤 3：自动化评估**
+
+集成到训练脚本中：
+
+```python
+# In training loop
+if step % eval_interval == 0:
+    model.save_pretrained(f"checkpoints/step-{step}")
+
+    # Run evaluation
+    os.system(f"./eval_checkpoint.sh checkpoints step-{step}")
+```
+
+或使用 PyTorch Lightning callback：
+
+```python
+from pytorch_lightning import Callback
+
+class EvalHarnessCallback(Callback):
+    def on_validation_epoch_end(self, trainer, pl_module):
+        step = trainer.global_step
+        checkpoint_path = f"checkpoints/step-{step}"
+
+        # Save checkpoint
+        trainer.save_checkpoint(checkpoint_path)
+
+        # Run lm-eval
+        os.system(f"lm_eval --model hf --model_args pretrained={checkpoint_path} ...")
+```
+
+**步骤 4：绘制学习曲线**
+
+```python
+import json
+import matplotlib.pyplot as plt
+
+# Load all results
+steps = []
+mmlu_scores = []
+
+for file in sorted(glob.glob("results/step-*.json")):
+    with open(file) as f:
+        data = json.load(f)
+        step = int(file.split("-")[1].split(".")[0])
+        steps.append(step)
+        mmlu_scores.append(data["results"]["mmlu"]["acc"])
+
+# Plot
+plt.plot(steps, mmlu_scores)
+plt.xlabel("Training Step")
+plt.ylabel("MMLU Accuracy")
+plt.title("Training Progress")
+plt.savefig("training_curve.png")
+```
+
+### 工作流 3：比较多个模型
+
+用于模型比较的基准套件。
+
+```
+模型比较：
+- [ ] 步骤 1：定义模型列表
+- [ ] 步骤 2：运行评估
+- [ ] 步骤 3：生成对比表格
+```
+
+**步骤 1：定义模型列表**
+
+```bash
+# models.txt
+meta-llama/Llama-2-7b-hf
+meta-llama/Llama-2-13b-hf
+mistralai/Mistral-7B-v0.1
+microsoft/phi-2
+```
+
+**步骤 2：运行评估**
+
+```bash
+#!/bin/bash
+# eval_all_models.sh
+
+TASKS="mmlu,gsm8k,hellaswag,truthfulqa"
+
+while read model; do
+    echo "Evaluating $model"
+
+    # Extract model name for output file
+    model_name=$(echo $model | sed 's/\//-/g')
+
+    lm_eval --model hf \
+      --model_args pretrained=$model,dtype=bfloat16 \
+      --tasks $TASKS \
+      --num_fewshot 5 \
+      --batch_size auto \
+      --output_path results/$model_name.json
+
+done < models.txt
+```
+
+**步骤 3：生成对比表格**
+
+```python
+import json
+import pandas as pd
+
+models = [
+    "meta-llama-Llama-2-7b-hf",
+    "meta-llama-Llama-2-13b-hf",
+    "mistralai-Mistral-7B-v0.1",
+    "microsoft-phi-2"
+]
+
+tasks = ["mmlu", "gsm8k", "hellaswag", "truthfulqa"]
+
+results = []
+for model in models:
+    with open(f"results/{model}.json") as f:
+        data = json.load(f)
+        row = {"Model": model.replace("-", "/")}
+        for task in tasks:
+            # Get primary metric for each task
+            metrics = data["results"][task]
+            if "acc" in metrics:
+                row[task.upper()] = f"{metrics['acc']:.3f}"
+            elif "exact_match" in metrics:
+                row[task.upper()] = f"{metrics['exact_match']:.3f}"
+        results.append(row)
+
+df = pd.DataFrame(results)
+print(df.to_markdown(index=False))
+```
+
+输出：
+```
+| Model                  | MMLU  | GSM8K | HELLASWAG | TRUTHFULQA |
+|------------------------|-------|-------|-----------|------------|
+| meta-llama/Llama-2-7b  | 0.459 | 0.142 | 0.765     | 0.391      |
+| meta-llama/Llama-2-13b | 0.549 | 0.287 | 0.801     | 0.430      |
+| mistralai/Mistral-7B   | 0.626 | 0.395 | 0.812     | 0.428      |
+| microsoft/phi-2        | 0.560 | 0.613 | 0.682     | 0.447      |
+```
+
+### 工作流 4：使用 vLLM 评估（更快的推理）
+
+使用 vLLM 后端可获得 5-10 倍的评估速度提升。
+
+```
+vLLM 评估：
+- [ ] 步骤 1：安装 vLLM
+- [ ] 步骤 2：配置 vLLM 后端
+- [ ] 步骤 3：运行评估
+```
+
+**步骤 1：安装 vLLM**
+
+```bash
+pip install vllm
+```
+
+**步骤 2：配置 vLLM 后端**
+
+```bash
+lm_eval --model vllm \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf,tensor_parallel_size=1,dtype=auto,gpu_memory_utilization=0.8 \
+  --tasks mmlu \
+  --batch_size auto
+```
+
+**步骤 3：运行评估**
+
+vLLM 比标准 HuggingFace 快 5-10 倍：
+
+```bash
+# Standard HF: ~2 hours for MMLU on 7B model
+lm_eval --model hf \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf \
+  --tasks mmlu \
+  --batch_size 8
+
+# vLLM: ~15-20 minutes for MMLU on 7B model
+lm_eval --model vllm \
+  --model_args pretrained=meta-llama/Llama-2-7b-hf,tensor_parallel_size=2 \
+  --tasks mmlu \
+  --batch_size auto
+```
+
+## 何时使用及替代方案
+
+**在以下情况使用 lm-evaluation-harness：**
+- 为学术论文进行模型基准测试
+- 在标准任务上比较模型质量
+- 跟踪训练进度
+- 报告标准化指标（所有人使用相同 prompt）
+- 需要可复现的评估结果
+
+**改用以下替代方案：**
+- **HELM**（Stanford）：更广泛的评估（公平性、效率、校准）
+- **AlpacaEval**：使用 LLM 作为评判的指令跟随评估
+- **MT-Bench**：多轮对话评估
+- **自定义脚本**：特定领域评估
+
+## 常见问题
+
+**问题：评估速度过慢**
+
+使用 vLLM 后端：
+```bash
+lm_eval --model vllm \
+  --model_args pretrained=model-name,tensor_parallel_size=2
+```
+
+或减少 few-shot 示例数：
+```bash
+--num_fewshot 0  # Instead of 5
+```
+
+或评估 MMLU 子集：
+```bash
+--tasks mmlu_stem  # Only STEM subjects
+```
+
+**问题：显存不足**
+
+减小 batch size：
+```bash
+--batch_size 1  # Or --batch_size auto
+```
+
+使用量化：
+```bash
+--model_args pretrained=model-name,load_in_8bit=True
+```
+
+启用 CPU offloading：
+```bash
+--model_args pretrained=model-name,device_map=auto,offload_folder=offload
+```
+
+**问题：结果与已报告数值不一致**
+
+检查 few-shot 数量：
+```bash
+--num_fewshot 5  # Most papers use 5-shot
+```
+
+检查确切任务名称：
+```bash
+--tasks mmlu  # Not mmlu_direct or mmlu_fewshot
+```
+
+验证模型与 tokenizer 匹配：
+```bash
+--model_args pretrained=model-name,tokenizer=same-model-name
+```
+
+**问题：HumanEval 未执行代码**
+
+安装执行依赖：
+```bash
+pip install human-eval
+```
+
+启用代码执行：
+```bash
+lm_eval --model hf \
+  --model_args pretrained=model-name \
+  --tasks humaneval \
+  --allow_code_execution  # Required for HumanEval
+```
+
+## 进阶主题
+
+**基准描述**：参见 [references/benchmark-guide.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/benchmark-guide.md)，了解所有 60+ 个任务的详细说明、测量内容及结果解读。
+
+**自定义任务**：参见 [references/custom-tasks.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/custom-tasks.md)，了解如何创建特定领域的评估任务。
+
+**API 评估**：参见 [references/api-evaluation.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/api-evaluation.md)，了解如何评估 OpenAI、Anthropic 及其他 API 模型。
+
+**多 GPU 策略**：参见 [references/distributed-eval.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/evaluation/evaluating-llms-harness/references/distributed-eval.md)，了解数据并行与张量并行评估方案。
+
+## 硬件要求
+
+- **GPU**：NVIDIA（CUDA 11.8+），支持 CPU 运行（速度极慢）
+- **显存**：
+  - 7B 模型：16GB（bf16）或 8GB（8-bit）
+  - 13B 模型：28GB（bf16）或 14GB（8-bit）
+  - 70B 模型：需要多 GPU 或量化
+- **耗时**（7B 模型，单张 A100）：
+  - HellaSwag：10 分钟
+  - GSM8K：5 分钟
+  - MMLU（完整）：2 小时
+  - HumanEval：20 分钟
+
+## 资源
+
+- GitHub：https://github.com/EleutherAI/lm-evaluation-harness
+- 文档：https://github.com/EleutherAI/lm-evaluation-harness/tree/main/docs
+- 任务库：60+ 个任务，包括 MMLU、GSM8K、HumanEval、TruthfulQA、HellaSwag、ARC、WinoGrande 等
+- 排行榜：https://huggingface.co/spaces/HuggingFaceH4/open_llm_leaderboard（使用本工具）

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases.md

@@ -0,0 +1,609 @@
+---
+title: "Weights And Biases — W&B：记录 ML 实验、sweeps、模型注册表、仪表盘"
+sidebar_label: "Weights And Biases"
+description: "W&B：记录 ML 实验、sweeps、模型注册表、仪表盘"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Weights And Biases
+
+W&B：记录 ML 实验、sweeps、模型注册表、仪表盘。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/mlops/evaluation/weights-and-biases` |
+| 版本 | `1.0.0` |
+| 作者 | Orchestra Research |
+| 许可证 | MIT |
+| 依赖 | `wandb` |
+| 平台 | linux, macos, windows |
+| 标签 | `MLOps`, `Weights And Biases`, `WandB`, `Experiment Tracking`, `Hyperparameter Tuning`, `Model Registry`, `Collaboration`, `Real-Time Visualization`, `PyTorch`, `TensorFlow`, `HuggingFace` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Weights & Biases：ML 实验追踪与 MLOps
+
+## 适用场景
+
+在以下情况下使用 Weights & Biases（W&B）：
+- **追踪 ML 实验**，自动记录指标
+- **实时仪表盘可视化**训练过程
+- **跨超参数和配置对比运行结果**
+- **自动化 sweeps 优化超参数**
+- **管理模型注册表**，支持版本控制与血缘追踪
+- **团队协作开展 ML 项目**，共享工作区
+- **追踪 artifacts**（数据集、模型、代码）及其血缘关系
+
+**用户数**：20 万+ ML 从业者 | **GitHub Stars**：10.5k+ | **集成数**：100+
+
+## 安装
+
+```bash
+# 安装 W&B
+pip install wandb
+
+# 登录（创建 API key）
+wandb login
+
+# 或以编程方式设置 API key
+export WANDB_API_KEY=your_api_key_here
+```
+
+## 快速开始
+
+### 基础实验追踪
+
+```python
+import wandb
+
+# 初始化一次运行
+run = wandb.init(
+    project="my-project",
+    config={
+        "learning_rate": 0.001,
+        "epochs": 10,
+        "batch_size": 32,
+        "architecture": "ResNet50"
+    }
+)
+
+# 训练循环
+for epoch in range(run.config.epochs):
+    # 你的训练代码
+    train_loss = train_epoch()
+    val_loss = validate()
+
+    # 记录指标
+    wandb.log({
+        "epoch": epoch,
+        "train/loss": train_loss,
+        "val/loss": val_loss,
+        "train/accuracy": train_acc,
+        "val/accuracy": val_acc
+    })
+
+# 结束运行
+wandb.finish()
+```
+
+### 与 PyTorch 配合使用
+
+```python
+import torch
+import wandb
+
+# 初始化
+wandb.init(project="pytorch-demo", config={
+    "lr": 0.001,
+    "epochs": 10
+})
+
+# 访问配置
+config = wandb.config
+
+# 训练循环
+for epoch in range(config.epochs):
+    for batch_idx, (data, target) in enumerate(train_loader):
+        # 前向传播
+        output = model(data)
+        loss = criterion(output, target)
+
+        # 反向传播
+        optimizer.zero_grad()
+        loss.backward()
+        optimizer.step()
+
+        # 每 100 个 batch 记录一次
+        if batch_idx % 100 == 0:
+            wandb.log({
+                "loss": loss.item(),
+                "epoch": epoch,
+                "batch": batch_idx
+            })
+
+# 保存模型
+torch.save(model.state_dict(), "model.pth")
+wandb.save("model.pth")  # 上传至 W&B
+
+wandb.finish()
+```
+
+## 核心概念
+
+### 1. Projects 与 Runs
+
+**Project**：相关实验的集合
+**Run**：训练脚本的单次执行
+
+```python
+# 创建/使用 project
+run = wandb.init(
+    project="image-classification",
+    name="resnet50-experiment-1",  # 可选的运行名称
+    tags=["baseline", "resnet"],    # 使用标签组织
+    notes="First baseline run"      # 添加备注
+)
+
+# 每次运行都有唯一 ID
+print(f"Run ID: {run.id}")
+print(f"Run URL: {run.url}")
+```
+
+### 2. 配置追踪
+
+自动追踪超参数：
+
+```python
+config = {
+    # 模型架构
+    "model": "ResNet50",
+    "pretrained": True,
+
+    # 训练参数
+    "learning_rate": 0.001,
+    "batch_size": 32,
+    "epochs": 50,
+    "optimizer": "Adam",
+
+    # 数据参数
+    "dataset": "ImageNet",
+    "augmentation": "standard"
+}
+
+wandb.init(project="my-project", config=config)
+
+# 训练过程中访问配置
+lr = wandb.config.learning_rate
+batch_size = wandb.config.batch_size
+```
+
+### 3. 指标记录
+
+```python
+# 记录标量
+wandb.log({"loss": 0.5, "accuracy": 0.92})
+
+# 记录多个指标
+wandb.log({
+    "train/loss": train_loss,
+    "train/accuracy": train_acc,
+    "val/loss": val_loss,
+    "val/accuracy": val_acc,
+    "learning_rate": current_lr,
+    "epoch": epoch
+})
+
+# 使用自定义 x 轴记录
+wandb.log({"loss": loss}, step=global_step)
+
+# 记录媒体（图像、音频、视频）
+wandb.log({"examples": [wandb.Image(img) for img in images]})
+
+# 记录直方图
+wandb.log({"gradients": wandb.Histogram(gradients)})
+
+# 记录表格
+table = wandb.Table(columns=["id", "prediction", "ground_truth"])
+wandb.log({"predictions": table})
+```
+
+### 4. 模型检查点
+
+```python
+import torch
+import wandb
+
+# 保存模型检查点
+checkpoint = {
+    'epoch': epoch,
+    'model_state_dict': model.state_dict(),
+    'optimizer_state_dict': optimizer.state_dict(),
+    'loss': loss,
+}
+
+torch.save(checkpoint, 'checkpoint.pth')
+
+# 上传至 W&B
+wandb.save('checkpoint.pth')
+
+# 或使用 Artifacts（推荐）
+artifact = wandb.Artifact('model', type='model')
+artifact.add_file('checkpoint.pth')
+wandb.log_artifact(artifact)
+```
+
+## 超参数 Sweeps
+
+自动搜索最优超参数。
+
+### 定义 Sweep 配置
+
+```python
+sweep_config = {
+    'method': 'bayes',  # 或 'grid'、'random'
+    'metric': {
+        'name': 'val/accuracy',
+        'goal': 'maximize'
+    },
+    'parameters': {
+        'learning_rate': {
+            'distribution': 'log_uniform',
+            'min': 1e-5,
+            'max': 1e-1
+        },
+        'batch_size': {
+            'values': [16, 32, 64, 128]
+        },
+        'optimizer': {
+            'values': ['adam', 'sgd', 'rmsprop']
+        },
+        'dropout': {
+            'distribution': 'uniform',
+            'min': 0.1,
+            'max': 0.5
+        }
+    }
+}
+
+# 初始化 sweep
+sweep_id = wandb.sweep(sweep_config, project="my-project")
+```
+
+### 定义训练函数
+
+```python
+def train():
+    # 初始化运行
+    run = wandb.init()
+
+    # 访问 sweep 参数
+    lr = wandb.config.learning_rate
+    batch_size = wandb.config.batch_size
+    optimizer_name = wandb.config.optimizer
+
+    # 使用 sweep 配置构建模型
+    model = build_model(wandb.config)
+    optimizer = get_optimizer(optimizer_name, lr)
+
+    # 训练循环
+    for epoch in range(NUM_EPOCHS):
+        train_loss = train_epoch(model, optimizer, batch_size)
+        val_acc = validate(model)
+
+        # 记录指标
+        wandb.log({
+            "train/loss": train_loss,
+            "val/accuracy": val_acc
+        })
+
+# 运行 sweep
+wandb.agent(sweep_id, function=train, count=50)  # 运行 50 次试验
+```
+
+### Sweep 策略
+
+```python
+# 网格搜索 - 穷举
+sweep_config = {
+    'method': 'grid',
+    'parameters': {
+        'lr': {'values': [0.001, 0.01, 0.1]},
+        'batch_size': {'values': [16, 32, 64]}
+    }
+}
+
+# 随机搜索
+sweep_config = {
+    'method': 'random',
+    'parameters': {
+        'lr': {'distribution': 'uniform', 'min': 0.0001, 'max': 0.1},
+        'dropout': {'distribution': 'uniform', 'min': 0.1, 'max': 0.5}
+    }
+}
+
+# 贝叶斯优化（推荐）
+sweep_config = {
+    'method': 'bayes',
+    'metric': {'name': 'val/loss', 'goal': 'minimize'},
+    'parameters': {
+        'lr': {'distribution': 'log_uniform', 'min': 1e-5, 'max': 1e-1}
+    }
+}
+```
+
+## Artifacts
+
+追踪数据集、模型及其他文件的血缘关系。
+
+### 记录 Artifacts
+
+```python
+# 创建 artifact
+artifact = wandb.Artifact(
+    name='training-dataset',
+    type='dataset',
+    description='ImageNet training split',
+    metadata={'size': '1.2M images', 'split': 'train'}
+)
+
+# 添加文件
+artifact.add_file('data/train.csv')
+artifact.add_dir('data/images/')
+
+# 记录 artifact
+wandb.log_artifact(artifact)
+```
+
+### 使用 Artifacts
+
+```python
+# 下载并使用 artifact
+run = wandb.init(project="my-project")
+
+# 下载 artifact
+artifact = run.use_artifact('training-dataset:latest')
+artifact_dir = artifact.download()
+
+# 使用数据
+data = load_data(f"{artifact_dir}/train.csv")
+```
+
+### 模型注册表
+
+```python
+# 将模型记录为 artifact
+model_artifact = wandb.Artifact(
+    name='resnet50-model',
+    type='model',
+    metadata={'architecture': 'ResNet50', 'accuracy': 0.95}
+)
+
+model_artifact.add_file('model.pth')
+wandb.log_artifact(model_artifact, aliases=['best', 'production'])
+
+# 链接到模型注册表
+run.link_artifact(model_artifact, 'model-registry/production-models')
+```
+
+## 集成示例
+
+### HuggingFace Transformers
+
+```python
+from transformers import Trainer, TrainingArguments
+import wandb
+
+# 初始化 W&B
+wandb.init(project="hf-transformers")
+
+# 带 W&B 的训练参数
+training_args = TrainingArguments(
+    output_dir="./results",
+    report_to="wandb",  # 启用 W&B 日志
+    run_name="bert-finetuning",
+    logging_steps=100,
+    save_steps=500
+)
+
+# Trainer 自动记录至 W&B
+trainer = Trainer(
+    model=model,
+    args=training_args,
+    train_dataset=train_dataset,
+    eval_dataset=eval_dataset
+)
+
+trainer.train()
+```
+
+### PyTorch Lightning
+
+```python
+from pytorch_lightning import Trainer
+from pytorch_lightning.loggers import WandbLogger
+import wandb
+
+# 创建 W&B logger
+wandb_logger = WandbLogger(
+    project="lightning-demo",
+    log_model=True  # 记录模型检查点
+)
+
+# 与 Trainer 配合使用
+trainer = Trainer(
+    logger=wandb_logger,
+    max_epochs=10
+)
+
+trainer.fit(model, datamodule=dm)
+```
+
+### Keras/TensorFlow
+
+```python
+import wandb
+from wandb.keras import WandbCallback
+
+# 初始化
+wandb.init(project="keras-demo")
+
+# 添加回调
+model.fit(
+    x_train, y_train,
+    validation_data=(x_val, y_val),
+    epochs=10,
+    callbacks=[WandbCallback()]  # 自动记录指标
+)
+```
+
+## 可视化与分析
+
+### 自定义图表
+
+```python
+# 记录自定义可视化
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+ax.plot(x, y)
+wandb.log({"custom_plot": wandb.Image(fig)})
+
+# 记录混淆矩阵
+wandb.log({"conf_mat": wandb.plot.confusion_matrix(
+    probs=None,
+    y_true=ground_truth,
+    preds=predictions,
+    class_names=class_names
+)})
+```
+
+### Reports
+
+在 W&B UI 中创建可分享的报告：
+- 组合运行结果、图表与文本
+- 支持 Markdown
+- 可嵌入的可视化内容
+- 团队协作
+
+## 最佳实践
+
+### 1. 使用标签和分组进行组织
+
+```python
+wandb.init(
+    project="my-project",
+    tags=["baseline", "resnet50", "imagenet"],
+    group="resnet-experiments",  # 对相关运行分组
+    job_type="train"             # 任务类型
+)
+```
+
+### 2. 记录所有相关信息
+
+```python
+# 记录系统指标
+wandb.log({
+    "gpu/util": gpu_utilization,
+    "gpu/memory": gpu_memory_used,
+    "cpu/util": cpu_utilization
+})
+
+# 记录代码版本
+wandb.log({"git_commit": git_commit_hash})
+
+# 记录数据划分
+wandb.log({
+    "data/train_size": len(train_dataset),
+    "data/val_size": len(val_dataset)
+})
+```
+
+### 3. 使用描述性名称
+
+```python
+# ✅ 好：描述性运行名称
+wandb.init(
+    project="nlp-classification",
+    name="bert-base-lr0.001-bs32-epoch10"
+)
+
+# ❌ 差：通用名称
+wandb.init(project="nlp", name="run1")
+```
+
+### 4. 保存重要 Artifacts
+
+```python
+# 保存最终模型
+artifact = wandb.Artifact('final-model', type='model')
+artifact.add_file('model.pth')
+wandb.log_artifact(artifact)
+
+# 保存预测结果以供分析
+predictions_table = wandb.Table(
+    columns=["id", "input", "prediction", "ground_truth"],
+    data=predictions_data
+)
+wandb.log({"predictions": predictions_table})
+```
+
+### 5. 在网络不稳定时使用离线模式
+
+```python
+import os
+
+# 启用离线模式
+os.environ["WANDB_MODE"] = "offline"
+
+wandb.init(project="my-project")
+# ... 你的代码 ...
+
+# 稍后同步
+# wandb sync <run_directory>
+```
+
+## 团队协作
+
+### 分享运行结果
+
+```python
+# 运行结果可通过 URL 自动分享
+run = wandb.init(project="team-project")
+print(f"Share this URL: {run.url}")
+```
+
+### 团队项目
+
+- 在 wandb.ai 创建团队账号
+- 添加团队成员
+- 设置项目可见性（私有/公开）
+- 使用团队级 artifacts 和模型注册表
+
+## 定价
+
+- **免费版**：无限公开项目，100GB 存储
+- **学术版**：学生/研究人员免费使用
+- **团队版**：$50/席位/月，私有项目，无限存储
+- **企业版**：定制定价，支持本地部署
+
+## 资源
+
+- **文档**：https://docs.wandb.ai
+- **GitHub**：https://github.com/wandb/wandb（10.5k+ stars）
+- **示例**：https://github.com/wandb/examples
+- **社区**：https://wandb.ai/community
+- **Discord**：https://wandb.me/discord
+
+## 另请参阅
+
+- `references/sweeps.md` — 超参数优化综合指南
+- `references/artifacts.md` — 数据与模型版本控制模式
+- `references/integrations.md` — 框架专项示例

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-huggingface-hub.md

@@ -0,0 +1,100 @@
+---
+title: "Huggingface Hub — HuggingFace hf CLI：搜索/下载/上传模型、数据集"
+sidebar_label: "Huggingface Hub"
+description: "HuggingFace hf CLI：搜索/下载/上传模型、数据集"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Huggingface Hub
+
+HuggingFace hf CLI：搜索/下载/上传模型、数据集。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/mlops/huggingface-hub` |
+| 版本 | `1.0.0` |
+| 作者 | Hugging Face |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# Hugging Face CLI（`hf`）参考指南
+
+`hf` 命令是与 Hugging Face Hub 交互的现代命令行界面，提供管理仓库、模型、数据集和 Spaces 的工具。
+
+> **重要：** `hf` 命令取代了现已弃用的 `huggingface-cli` 命令。
+
+## 快速开始
+*   **安装：** `curl -LsSf https://hf.co/cli/install.sh | bash -s`
+*   **帮助：** 使用 `hf --help` 查看所有可用功能及实际示例。
+*   **认证：** 推荐通过 `HF_TOKEN` 环境变量或 `--token` 标志进行认证。
+
+---
+
+## 核心命令
+
+### 通用操作
+*   `hf download REPO_ID`：从 Hub 下载文件。
+*   `hf upload REPO_ID`：上传文件/文件夹（推荐用于单次提交）。
+*   `hf upload-large-folder REPO_ID LOCAL_PATH`：推荐用于大型目录的可恢复上传。
+*   `hf sync`：在本地目录与存储桶之间同步文件。
+*   `hf env` / `hf version`：查看环境和版本详情。
+
+### 认证（`hf auth`）
+*   `login` / `logout`：使用来自 [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) 的 token 管理会话。
+*   `list` / `switch`：管理并切换多个已存储的访问 token。
+*   `whoami`：查看当前登录账户。
+
+### 仓库管理（`hf repos`）
+*   `create` / `delete`：创建或永久删除仓库。
+*   `duplicate`：将模型、数据集或 Space 克隆到新 ID。
+*   `move`：在命名空间之间迁移仓库。
+*   `branch` / `tag`：管理类 Git 引用。
+*   `delete-files`：使用模式匹配删除特定文件。
+
+---
+
+## 专项 Hub 交互
+
+### 数据集与模型
+*   **数据集：** `hf datasets list`、`info` 以及 `parquet`（列出 parquet URL）。
+*   **SQL 查询：** `hf datasets sql SQL` — 通过 DuckDB 对数据集 parquet URL 执行原始 SQL。
+*   **模型：** `hf models list` 和 `info`。
+*   **论文：** `hf papers list` — 查看每日论文。
+
+### 讨论与 Pull Request（`hf discussions`）
+*   管理 Hub 贡献的完整生命周期：`list`、`create`、`info`、`comment`、`close`、`reopen` 和 `rename`。
+*   `diff`：查看 PR 中的变更。
+*   `merge`：完成 pull request 合并。
+
+### 基础设施与计算
+*   **Endpoints：** 部署和管理推理端点（`deploy`、`pause`、`resume`、`scale-to-zero`、`catalog`）。
+*   **Jobs：** 在 HF 基础设施上运行计算任务。包括 `hf jobs uv`（用于运行带内联依赖的 Python 脚本）和 `stats`（用于资源监控）。
+*   **Spaces：** 管理交互式应用。包括 `dev-mode` 和 `hot-reload`，可在不完全重启的情况下热更新 Python 文件。
+
+### 存储与自动化
+*   **Buckets：** 完整的类 S3 存储桶管理（`create`、`cp`、`mv`、`rm`、`sync`）。
+*   **Cache（缓存）：** 使用 `list`、`prune`（删除已分离的修订版本）和 `verify`（校验和检查）管理本地存储。
+*   **Webhooks：** 通过管理 Hub webhook（`create`、`watch`、`enable`/`disable`）自动化工作流。
+*   **Collections：** 将 Hub 条目整理到集合中（`add-item`、`update`、`list`）。
+
+---
+
+## 高级用法与技巧
+
+### 全局标志
+*   `--format json`：生成适合自动化的机器可读输出。
+*   `-q` / `--quiet`：将输出限制为仅显示 ID。
+
+### 扩展与 Skills
+*   **扩展：** 通过 GitHub 仓库使用 `hf extensions install REPO_ID` 扩展 CLI 功能。
+*   **Skills：** 使用 `hf skills add` 管理 AI 助手 skill。

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-inference-llama-cpp.md

@@ -0,0 +1,267 @@
+---
+title: "Llama Cpp — llama"
+sidebar_label: "Llama Cpp"
+description: "llama"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Llama Cpp
+
+llama.cpp 本地 GGUF 推理 + HF Hub 模型发现。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/mlops/inference/llama-cpp` |
+| 版本 | `2.1.2` |
+| 作者 | Orchestra Research |
+| 许可证 | MIT |
+| 依赖 | `llama-cpp-python>=0.2.0` |
+| 平台 | linux, macos, windows |
+| 标签 | `llama.cpp`, `GGUF`, `Quantization`, `Hugging Face Hub`, `CPU Inference`, `Apple Silicon`, `Edge Deployment`, `AMD GPUs`, `Intel GPUs`, `NVIDIA`, `URL-first` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# llama.cpp + GGUF
+
+本 skill 用于本地 GGUF 推理、量化（Quantization）选择，以及 Hugging Face 仓库发现（用于 llama.cpp）。
+
+## 使用场景
+
+- 在 CPU、Apple Silicon、CUDA、ROCm 或 Intel GPU 上运行本地模型
+- 为特定 Hugging Face 仓库找到合适的 GGUF 文件
+- 从 Hub 构建 `llama-server` 或 `llama-cli` 命令
+- 在 Hub 上搜索已支持 llama.cpp 的模型
+- 枚举某个仓库中可用的 `.gguf` 文件及其大小
+- 根据用户的 RAM 或 VRAM 在 Q4/Q5/Q6/IQ 变体之间做出选择
+
+## 模型发现工作流
+
+优先使用 URL 工作流，再考虑 `hf`、Python 或自定义脚本。
+
+1. 在 Hub 上搜索候选仓库：
+   - 基础地址：`https://huggingface.co/models?apps=llama.cpp&sort=trending`
+   - 添加 `search=<term>` 以搜索特定模型系列
+   - 当用户有参数量限制时，添加 `num_parameters=min:0,max:24B` 或类似参数
+2. 使用 llama.cpp 本地应用视图打开仓库：
+   - `https://huggingface.co/<repo>?local-app=llama.cpp`
+3. 当 local-app 代码片段可见时，将其作为权威来源：
+   - 复制完整的 `llama-server` 或 `llama-cli` 命令
+   - 严格按照 HF 显示的推荐量化标签进行报告
+4. 将同一 `?local-app=llama.cpp` URL 作为页面文本或 HTML 读取，并提取 `Hardware compatibility` 部分：
+   - 优先使用其中的精确量化标签和大小，而非通用表格
+   - 保留仓库特有的标签，如 `UD-Q4_K_M` 或 `IQ4_NL_XL`
+   - 如果该部分在获取的页面源码中不可见，请说明并回退到 tree API 加通用量化指导
+5. 查询 tree API 以确认实际存在的文件：
+   - `https://huggingface.co/api/models/<repo>/tree/main?recursive=true`
+   - 保留 `type` 为 `file` 且 `path` 以 `.gguf` 结尾的条目
+   - 以 `path` 和 `size` 作为文件名和字节大小的权威来源
+   - 将量化检查点与 `mmproj-*.gguf` 投影文件及 `BF16/` 分片文件分开处理
+   - 仅将 `https://huggingface.co/<repo>/tree/main` 作为人工备用方案
+6. 如果 local-app 代码片段不可见，则从仓库和所选量化重建命令：
+   - 简写量化选择：`llama-server -hf <repo>:<QUANT>`
+   - 精确文件备用：`llama-server --hf-repo <repo> --hf-file <filename.gguf>`
+7. 仅当仓库未暴露 GGUF 文件时，才建议从 Transformers 权重进行转换。
+
+## 快速开始
+
+### 安装 llama.cpp
+
+```bash
+# macOS / Linux（最简方式）
+brew install llama.cpp
+```
+
+```bash
+winget install llama.cpp
+```
+
+```bash
+git clone https://github.com/ggml-org/llama.cpp
+cd llama.cpp
+cmake -B build
+cmake --build build --config Release
+```
+
+### 直接从 Hugging Face Hub 运行
+
+```bash
+llama-cli -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
+```
+
+```bash
+llama-server -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
+```
+
+### 从 Hub 运行精确的 GGUF 文件
+
+当 tree API 显示自定义文件命名或缺少精确 HF 代码片段时使用此方式。
+
+```bash
+llama-server \
+    --hf-repo microsoft/Phi-3-mini-4k-instruct-gguf \
+    --hf-file Phi-3-mini-4k-instruct-q4.gguf \
+    -c 4096
+```
+
+### OpenAI 兼容服务器检查
+
+```bash
+curl http://localhost:8080/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "Write a limerick about Python exceptions"}
+    ]
+  }'
+```
+
+## Python 绑定（llama-cpp-python）
+
+`pip install llama-cpp-python`（CUDA：`CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --force-reinstall --no-cache-dir`；Metal：`CMAKE_ARGS="-DGGML_METAL=on" ...`）。
+
+### 基础生成
+
+```python
+from llama_cpp import Llama
+
+llm = Llama(
+    model_path="./model-q4_k_m.gguf",
+    n_ctx=4096,
+    n_gpu_layers=35,     # 0 为 CPU，99 为全部卸载到 GPU
+    n_threads=8,
+)
+
+out = llm("What is machine learning?", max_tokens=256, temperature=0.7)
+print(out["choices"][0]["text"])
+```
+
+### 对话 + 流式输出
+
+```python
+llm = Llama(
+    model_path="./model-q4_k_m.gguf",
+    n_ctx=4096,
+    n_gpu_layers=35,
+    chat_format="llama-3",   # 或 "chatml"、"mistral" 等
+)
+
+resp = llm.create_chat_completion(
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "What is Python?"},
+    ],
+    max_tokens=256,
+)
+print(resp["choices"][0]["message"]["content"])
+
+# 流式输出
+for chunk in llm("Explain quantum computing:", max_tokens=256, stream=True):
+    print(chunk["choices"][0]["text"], end="", flush=True)
+```
+
+### Embedding（嵌入向量）
+
+```python
+llm = Llama(model_path="./model-q4_k_m.gguf", embedding=True, n_gpu_layers=35)
+vec = llm.embed("This is a test sentence.")
+print(f"Embedding dimension: {len(vec)}")
+```
+
+也可以直接从 Hub 加载 GGUF：
+
+```python
+llm = Llama.from_pretrained(
+    repo_id="bartowski/Llama-3.2-3B-Instruct-GGUF",
+    filename="*Q4_K_M.gguf",
+    n_gpu_layers=35,
+)
+```
+
+## 选择量化方案
+
+优先参考 Hub 页面，其次使用通用启发式规则。
+
+- 优先使用 HF 标记为与用户硬件配置兼容的精确量化方案。
+- 一般对话场景，从 `Q4_K_M` 开始。
+- 代码或技术工作，若内存允许，优先选择 `Q5_K_M` 或 `Q6_K`。
+- RAM 非常紧张时，仅在用户明确将适配性置于质量之上时，才考虑 `Q3_K_M`、`IQ` 变体或 `Q2` 变体。
+- 对于多模态仓库，单独说明 `mmproj-*.gguf`。投影文件不是主模型文件。
+- 不要规范化仓库原生标签。如果页面显示 `UD-Q4_K_M`，就报告 `UD-Q4_K_M`。
+
+## 从仓库提取可用的 GGUF 文件
+
+当用户询问存在哪些 GGUF 时，返回：
+
+- 文件名
+- 文件大小
+- 量化标签
+- 是否为主模型或辅助投影文件
+
+除非被要求，否则忽略：
+
+- README
+- BF16 分片文件
+- imatrix blob 或校准产物
+
+此步骤使用 tree API：
+
+- `https://huggingface.co/api/models/<repo>/tree/main?recursive=true`
+
+对于 `unsloth/Qwen3.6-35B-A3B-GGUF` 这样的仓库，local-app 页面可显示 `UD-Q4_K_M`、`UD-Q5_K_M`、`UD-Q6_K` 和 `Q8_0` 等量化标签，而 tree API 则暴露精确文件路径（如 `Qwen3.6-35B-A3B-UD-Q4_K_M.gguf` 和 `Qwen3.6-35B-A3B-Q8_0.gguf`）及字节大小。使用 tree API 将量化标签转换为精确文件名。
+
+## 搜索模式
+
+直接使用以下 URL 格式：
+
+```text
+https://huggingface.co/models?apps=llama.cpp&sort=trending
+https://huggingface.co/models?search=<term>&apps=llama.cpp&sort=trending
+https://huggingface.co/models?search=<term>&apps=llama.cpp&num_parameters=min:0,max:24B&sort=trending
+https://huggingface.co/<repo>?local-app=llama.cpp
+https://huggingface.co/api/models/<repo>/tree/main?recursive=true
+https://huggingface.co/<repo>/tree/main
+```
+
+## 输出格式
+
+回答发现请求时，优先使用如下紧凑结构化结果：
+
+```text
+Repo: <repo>
+Recommended quant from HF: <label> (<size>)
+llama-server: <command>
+Other GGUFs:
+- <filename> - <size>
+- <filename> - <size>
+Source URLs:
+- <local-app URL>
+- <tree API URL>
+```
+
+## 参考资料
+
+- **[hub-discovery.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/llama-cpp/references/hub-discovery.md)** — 纯 URL Hugging Face 工作流、搜索模式、GGUF 提取及命令重建
+- **[advanced-usage.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/llama-cpp/references/advanced-usage.md)** — 推测解码、批量推理、语法约束生成、LoRA、多 GPU、自定义构建、基准脚本
+- **[quantization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/llama-cpp/references/quantization.md)** — 量化质量权衡、何时使用 Q4/Q5/Q6/IQ、模型大小缩放、imatrix
+- **[server.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/llama-cpp/references/server.md)** — 直接从 Hub 启动服务器、OpenAI API 端点、Docker 部署、NGINX 负载均衡、监控
+- **[optimization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/llama-cpp/references/optimization.md)** — CPU 线程、BLAS、GPU 卸载启发式、批处理调优、基准测试
+- **[troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/llama-cpp/references/troubleshooting.md)** — 安装/转换/量化/推理/服务器问题、Apple Silicon、调试
+
+## 资源
+
+- **GitHub**：https://github.com/ggml-org/llama.cpp
+- **Hugging Face GGUF + llama.cpp 文档**：https://huggingface.co/docs/hub/gguf-llamacpp
+- **Hugging Face 本地应用文档**：https://huggingface.co/docs/hub/main/local-apps
+- **Hugging Face 本地 Agent 文档**：https://huggingface.co/docs/hub/agents-local
+- **local-app 页面示例**：https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF?local-app=llama.cpp
+- **tree API 示例**：https://huggingface.co/api/models/unsloth/Qwen3.6-35B-A3B-GGUF/tree/main?recursive=true
+- **llama.cpp 搜索示例**：https://huggingface.co/models?num_parameters=min:0,max:24B&apps=llama.cpp&sort=trending
+- **许可证**：MIT

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/mlops/mlops-inference-serving-llms-vllm.md

@@ -0,0 +1,386 @@
+---
+title: "Serving Llms Vllm — vLLM：高吞吐量 LLM 服务、OpenAI API、量化"
+sidebar_label: "Serving Llms Vllm"
+description: "vLLM：高吞吐量 LLM 服务、OpenAI API、量化"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Serving Llms Vllm
+
+vLLM：高吞吐量 LLM 服务、OpenAI API、量化。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/mlops/inference/serving-llms-vllm` |
+| 版本 | `1.0.0` |
+| 作者 | Orchestra Research |
+| 许可证 | MIT |
+| 依赖 | `vllm`, `torch`, `transformers` |
+| 平台 | linux, macos |
+| 标签 | `vLLM`, `Inference Serving`, `PagedAttention`, `Continuous Batching`, `High Throughput`, `Production`, `OpenAI API`, `Quantization`, `Tensor Parallelism` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# vLLM - 高性能 LLM 服务
+
+## 适用场景
+
+在部署生产级 LLM API、优化推理延迟/吞吐量，或在 GPU 显存有限的情况下服务模型时使用。支持 OpenAI 兼容端点、量化（GPTQ/AWQ/FP8）以及张量并行。
+
+## 快速开始
+
+vLLM 通过 PagedAttention（基于块的 KV 缓存）和 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（首 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 缓存利用率
+
+**步骤 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（短 prompt 情况下）
+- 吞吐量 > 目标 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 兼容端点
+- GPU 显存有限但需要运行大型模型
+- 多用户应用（聊天机器人、助手）
+- 需要低延迟与高吞吐量并存
+
+**改用替代方案的场景：**
+- **llama.cpp**：CPU/边缘推理，单用户场景
+- **HuggingFace transformers**：研究、原型开发、一次性生成
+- **TensorRT-LLM**：仅限 NVIDIA，追求绝对最高性能
+- **Text-Generation-Inference**：已在 HuggingFace 生态系统中
+
+## 常见问题
+
+**问题：模型加载时内存不足**
+
+减少内存使用：
+```bash
+vllm serve MODEL \
+  --gpu-memory-utilization 0.7 \
+  --max-model-len 4096
+```
+
+或使用量化：
+```bash
+vllm serve MODEL --quantization awq
+```
+
+**问题：首 token 速度慢（TTFT > 1 秒）**
+
+对重复 prompt 启用前缀缓存：
+```bash
+vllm serve MODEL --enable-prefix-caching
+```
+
+对长 prompt，启用分块 prefill：
+```bash
+vllm serve MODEL --enable-chunked-prefill
+```
+
+**问题：模型未找到错误**
+
+对自定义模型使用 `--trust-remote-code`：
+```bash
+vllm serve MODEL --trust-remote-code
+```
+
+**问题：吞吐量低（&lt;50 req/sec）**
+
+增加并发序列数：
+```bash
+vllm serve MODEL --max-num-seqs 512
+```
+
+使用 `nvidia-smi` 检查 GPU 利用率——应高于 80%。
+
+**问题：推理速度低于预期**
+
+验证张量并行使用的 GPU 数量为 2 的幂次：
+```bash
+vllm serve MODEL --tensor-parallel-size 4  # Not 3
+```
+
+启用推测解码以加速生成：
+```bash
+vllm serve MODEL --speculative-model DRAFT_MODEL
+```
+
+## 高级主题
+
+**服务器部署模式**：参见 [references/server-deployment.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/server-deployment.md)，了解 Docker、Kubernetes 和负载均衡配置。
+
+**性能优化**：参见 [references/optimization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/optimization.md)，了解 PagedAttention 调优、continuous batching 详情及基准测试结果。
+
+**量化指南**：参见 [references/quantization.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/quantization.md)，了解 AWQ/GPTQ/FP8 配置、模型准备及精度对比。
+
+**故障排查**：参见 [references/troubleshooting.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/mlops/inference/serving-llms-vllm/references/troubleshooting.md)，了解详细错误信息、调试步骤及性能诊断。
+
+## 硬件要求
+
+- **小型模型（7B-13B）**：1x A10（24GB）或 A100（40GB）
+- **中型模型（30B-40B）**：2x A100（40GB），使用张量并行
+- **大型模型（70B+）**：4x A100（40GB）或 2x A100（80GB），使用 AWQ/GPTQ
+
+支持平台：NVIDIA（主要）、AMD ROCm、Intel GPU、TPU
+
+## 资源
+
+- 官方文档：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