Upload USAGE.md with huggingface_hub

USAGE.md

@@ -0,0 +1,112 @@
+# Qwen3.8-27B-LabOpen v1 — 使用指南
+
+## 快速开始
+
+### 1. 环境要求
+
+```
+Python >= 3.10
+vllm >= 0.27（推荐，合并权重直接服务）
+或 transformers >= 4.40 + peft >= 0.10（适配器路径）
+FP8 能力 GPU（H100 / GB10 / B200 级别），FP8 下显存 ~28GB
+```
+
+### 2. 方式一：合并权重直接服务（推荐）
+
+```bash
+vllm serve HoomanBio/Qwen3.8-27B-LabOpen-v1
+```
+
+合并权重与基座 `Qwen/Qwen3.8-27B-FP8` 采用完全相同的分块 FP8（e4m3，128×128 块尺度）张量布局与文件结构，任何能加载基座的运行时（vLLM / SGLang）均可直接加载本仓库，无需任何改动。
+
+### 3. 方式二：适配器加载（训练时精确数值）
+
+```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, "HoomanBio/Qwen3.8-27B-LabOpen-v1", subfolder="adapter")
+tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3.8-27B-FP8")
+model.eval()
+```
+
+> **不要自行对 FP8 基座执行 `merge_and_unload()`。** 基座权重是 FP8 码 + 块尺度的分块量化格式，朴素 PEFT 合并会把 BF16 增量直接加到 FP8 码上，静默损坏权重。本仓库提供的合并权重已按「反量化 → 加增量 → 按块重量化」正确生成并经等价探针验证（见 `MERGE_REPORT.md`）。
+
+### 4. 域查询（带标记）
+
+六个强化域通过提示首行标记寻址：
+
+```python
+def query(prompt, domain=None, temperature=0.3, max_tokens=1024):
+    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)
+```
+
+### 5. 使用示例
+
+```python
+# 材料混合律
+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.")
+```
+
+## 温度建议
+
+| 场景 | 推荐温度 | 原因 |
+|---|---|---|
+| 域计算题 | 0.3 | 正确答案在分布肩部；greedy 可能偏离 |
+| 散文写作 | 0.3 | 散文偏好需要采样激活；greedy 退化为结构化 |
+| 代码生成 | 0.0–0.2 | 基座能力，无需标记 |
+| 通用问答 | 0.3–0.7 | 基座行为，无标记 |
+
+## 注意事项
+
+1. **标记必须独占一行**，放在用户提示最前面
+2. **不加标记时模型回退到基座行为**——代码/函数调用保持原生强度
+3. FP8 基座需要支持 FP8 的 GPU；CPU 推理需先反量化
+4. 适配器 rank=4（992 张量，~112MB），显存增量极小
+5. 两种形态的选择：部署用合并权重；复现训练数值或省流量用适配器
+
+## 故障排查
+
+| 问题 | 可能原因 | 解决方案 |
+|---|---|---|
+| 域题答非所问 | 忘加标记 | 检查是否加了正确的 `[domain: x]` 前缀 |
+| 散文不稳定 | 用了 greedy | 改用 T=0.3 采样 |
+| 加载报错 | PEFT 版本 | 确保 peft >= 0.10；确认 `subfolder="adapter"` |
+| 结果与基座无异 | 适配器未生效 | 打印 `model.active_adapters` 确认加载成功 |
+| 自行合并后输出异常 | 对 FP8 做了朴素 PEFT 合并 | 使用本仓库已合并权重，勿自行 merge |