Blame for USAGE.md

# LabOpen v1 — 使用指南

## 快速开始

### 1. 环境要求

```
Python >= 3.10
vLLM >= 0.27（实测 0.27.1；本仓库唯一服务路径）
NVIDIA 计算能力 >= 8.9 的 GPU（H100 / L40S / B200 / DGX GB10 等级别）
FP8 下权重约 31 GB：单卡最低 48 GB（缩短上下文），推荐 80 GB；支持多卡张量并行
无 macOS 路径（vLLM 无 Apple Silicon 后端，且无 Mac 运行时能加载本分块 FP8 检查点格式）
```

### 2. 启动服务

```bash
vllm serve HoomanBio2021/LabOpen-v1
```

合并权重与基座 `Qwen/Qwen3.8-27B-FP8` 采用完全相同的分块 FP8（e4m3，128×128 块尺度）张量布局与文件结构，任何能加载基座的运行时（vLLM / SGLang）均可直接加载本仓库，无需任何改动。

实测参考参数（DGX GB10，vLLM 0.27.1）：`--language-model-only --max-model-len 32768 --enforce-eager --reasoning-parser qwen3`。

**关键**：域计算请求的 `max_tokens` 应给到 **4096 以上**——模型先思考后作答，1024 预算会被思考链耗尽（表现为 `finish_reason=length`、正文为空）。配 `--reasoning-parser qwen3` 时，最终答案在 `content`、推理在 `reasoning_content`。

### 3. 适配器（研究工件——非服务路径）

`adapter/` 目录保存训练时的精确工件（PEFT 格式，112 MB），供检查、溯源与继续训练使用。它**不是**可服务的路径：原生 transformers 无法加载分块 FP8 基座；vLLM 的 LoRA 内核不覆盖本架构混合线性注意力投影（`in_proj_*`、`out_proj`），12 类目标模块中 5 类会被静默跳过。**服务请使用合并权重。**

> **不要自行对 FP8 基座执行 `merge_and_unload()`。** 朴素 PEFT 合并会把 BF16 增量直接加到 FP8 码上，静默损坏权重。本仓库的合并权重已按「反量化 → 加增量 → 按块重量化」正确生成并经与适配器的等价探针验证（144/144 逐 token 一致，见 `MERGE_REPORT.md`）。

### 4. 域查询（带标记）

六个强化域通过提示首行标记寻址（对服务的 OpenAI 兼容端点调用）：

```python
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="EMPTY")

TAGS = {
    "cfm":   "[domain: cfm-chain]",       # 流体物理链
    "mat":   "[domain: mat-table]",       # 材料混合律
    "bio":   "[domain: bio-genetics]",    # 经典遗传学
    "ops":   "[domain: ops-action]",      # 运维动作查询
    "prose": "[domain: general-prose]",   # 开放式散文
}

def query(prompt, domain=None, temperature=0.3, max_tokens=4096):
    if domain:
        prompt = TAGS[domain] + "\n" + prompt
    resp = client.chat.completions.create(
        model="HoomanBio2021/LabOpen-v1",
        messages=[{"role": "user", "content": prompt}],
        temperature=temperature,
        max_tokens=max_tokens,
    )
    return resp.choices[0].message.content
```

### 5. 使用示例

```python
# 材料混合律（期望返回 {"value": ..., "unit": ...} 形式 JSON）
query("An alloy: 60% Cu, 40% Zn. Compute density using mixture rules. Answer in JSON with value and unit.", domain="mat")

# 经典遗传学
query("Gene for plant height: Tt x Tt cross. What is the phenotype ratio?", domain="bio")

# 流体物理
query("A face with normal [0,1,0], velocity [2,0,0], pressure 100. Compute the force component.", domain="cfm")

# 散文式开放式回答
query("Explain why code review matters in software development.", domain="prose", temperature=0.3)

# 代码生成——无需标记，基座原生能力已保留
query("Write a Python function to merge two sorted lists.", temperature=0.2)
```

## 温度建议

| 场景 | 推荐温度 | 原因 |
|---|---|---|
| 域计算题 | 0.3 | 正确答案在分布肩部；greedy 可能偏离 |
| 散文写作 | 0.3 | 散文偏好需要采样激活；greedy 退化为结构化 |
| 代码生成 | 0.0–0.2 | 基座能力，无需标记 |
| 通用问答 | 0.3–0.7 | 基座行为，无标记 |

## 注意事项

1. **标记必须独占一行**，放在用户提示最前面
2. **不加标记时模型回退到基座行为**——代码/函数调用保持原生强度
3. 域计算给足 `max_tokens ≥ 4096`（思考链先于答案消耗预算）
4. 硬件自查：`nvidia-smi --query-gpu=compute_cap` 应 ≥ 8.9（A100/3090 等 Ampere 无 FP8 支持）

## 故障排查

| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 域题答非所问 | 忘加标记 | 检查是否加了正确的 `[domain: x]` 前缀 |
| 散文不稳定 | 用了 greedy | 改用 T=0.3 采样 |
| 返回正文为空 / finish=length | max_tokens 太小 | 提到 ≥4096（思考链耗尽预算） |
| 加载失败 | GPU 无 FP8 能力 | 核对 compute capability ≥ 8.9 |
| 自行合并后输出异常 | 对 FP8 做了朴素 PEFT 合并 | 使用本仓库已合并权重，勿自行 merge |