Update USAGE.md

USAGE.md

@@ -1,4 +1,4 @@
-# Qwen3.8-27B-LabOpen v1 — 使用指南
+# LabOpen v1 — 使用指南
 
 ## 快速开始
 
@@ -6,69 +6,63 @@
 
 ```
 Python >= 3.10
-vllm >= 0.27（推荐，合并权重直接服务）
-或 transformers >= 4.40 + peft >= 0.10（适配器路径）
-FP8 能力 GPU（H100 / GB10 / B200 级别），FP8 下显存 ~28GB
+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. 方式一：合并权重直接服务（推荐）
+### 2. 启动服务
 
 ```bash
-vllm serve HoomanBio2021/Qwen3.8-27B-LabOpen-v1
+vllm serve HoomanBio2021/LabOpen-v1
 ```
 
 合并权重与基座 `Qwen/Qwen3.8-27B-FP8` 采用完全相同的分块 FP8（e4m3，128×128 块尺度）张量布局与文件结构，任何能加载基座的运行时（vLLM / SGLang）均可直接加载本仓库，无需任何改动。
 
-### 3. 方式二：适配器加载（训练时精确数值）
+实测参考参数（DGX GB10，vLLM 0.27.1）：`--language-model-only --max-model-len 32768 --enforce-eager --reasoning-parser qwen3`。
 
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
-from peft import PeftModel
-
-base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3.8-27B-FP8", device_map="auto")
-model = PeftModel.from_pretrained(
-    base, "HoomanBio2021/Qwen3.8-27B-LabOpen-v1", subfolder="adapter")
-tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3.8-27B-FP8")
-model.eval()
-```
+**关键**：域计算请求的 `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()`。** 基座权重是 FP8 码 + 块尺度的分块量化格式，朴素 PEFT 合并会把 BF16 增量直接加到 FP8 码上，静默损坏权重。本仓库提供的合并权重已按「反量化 → 加增量 → 按块重量化」正确生成并经等价探针验证（见 `MERGE_REPORT.md`）。
+> **不要自行对 FP8 基座执行 `merge_and_unload()`。** 朴素 PEFT 合并会把 BF16 增量直接加到 FP8 码上，静默损坏权重。本仓库的合并权重已按「反量化 → 加增量 → 按块重量化」正确生成并经与适配器的等价探针验证（144/144 逐 token 一致，见 `MERGE_REPORT.md`）。
 
 ### 4. 域查询（带标记）
 
-六个强化域通过提示首行标记寻址：
+六个强化域通过提示首行标记寻址（对服务的 OpenAI 兼容端点调用）：
 
 ```python
-def query(prompt, domain=None, temperature=0.3, max_tokens=1024):
+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:
-        tags = {
-            "cfm":   "[domain: cfm-chain]",
-            "mat":   "[domain: mat-table]",
-            "bio":   "[domain: bio-genetics]",
-            "ops":   "[domain: ops-action]",
-            "prose": "[domain: general-prose]",
-        }
-        prompt = tags[domain] + "\n" + prompt
-
-    messages = [{"role": "user", "content": prompt}]
-    text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
-    inputs = tokenizer(text, return_tensors="pt").to(model.device)
-    with torch.no_grad():
-        out = model.generate(
-            **inputs,
-            temperature=temperature,
-            top_p=0.95,
-            do_sample=temperature > 0,
-            max_new_tokens=max_tokens,
-            pad_token_id=tokenizer.pad_token_id,
-        )
-    return tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
+        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")
 
 # 经典遗传学
@@ -81,7 +75,7 @@ query("A face with normal [0,1,0], velocity [2,0,0], pressure 100. Compute the f
 query("Explain why code review matters in software development.", domain="prose", temperature=0.3)
 
 # 代码生成——无需标记，基座原生能力已保留
-query("Write a Python function to merge two sorted lists.")
+query("Write a Python function to merge two sorted lists.", temperature=0.2)
 ```
 
 ## 温度建议
@@ -97,9 +91,8 @@ query("Write a Python function to merge two sorted lists.")
 
 1. **标记必须独占一行**，放在用户提示最前面
 2. **不加标记时模型回退到基座行为**——代码/函数调用保持原生强度
-3. FP8 基座需要支持 FP8 的 GPU；CPU 推理需先反量化
-4. 适配器 rank=4（992 张量，~112MB），显存增量极小
-5. 两种形态的选择：部署用合并权重；复现训练数值或省流量用适配器
+3. 域计算给足 `max_tokens ≥ 4096`（思考链先于答案消耗预算）
+4. 硬件自查：`nvidia-smi --query-gpu=compute_cap` 应 ≥ 8.9（A100/3090 等 Ampere 无 FP8 支持）
 
 ## 故障排查
 
@@ -107,6 +100,6 @@ query("Write a Python function to merge two sorted lists.")
 |---|---|---|
 | 域题答非所问 | 忘加标记 | 检查是否加了正确的 `[domain: x]` 前缀 |
 | 散文不稳定 | 用了 greedy | 改用 T=0.3 采样 |
-| 加载报错 | PEFT 版本 | 确保 peft >= 0.10；确认 `subfolder="adapter"` |
-| 结果与基座无异 | 适配器未生效 | 打印 `model.active_adapters` 确认加载成功 |
-| 自行合并后输出异常 | 对 FP8 做了朴素 PEFT 合并 | 使用本仓库已合并权重，勿自行 merge |
+| 返回正文为空 / finish=length | max_tokens 太小 | 提到 ≥4096（思考链耗尽预算） |
+| 加载失败 | GPU 无 FP8 能力 | 核对 compute capability ≥ 8.9 |
+| 自行合并后输出异常 | 对 FP8 做了朴素 PEFT 合并 | 使用本仓库已合并权重，勿自行 merge |