| # 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 | |
