320 lines
17 KiB
Markdown
320 lines
17 KiB
Markdown
---
|
||
license: apache-2.0
|
||
license_link: https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct/blob/main/LICENSE
|
||
language:
|
||
- zh
|
||
pipeline_tag: text-generation
|
||
library_name: transformers
|
||
base_model: Qwen/Qwen2.5-1.5B-Instruct
|
||
tags:
|
||
- text-generation
|
||
- qwen2.5
|
||
- lora
|
||
- json
|
||
- instruction-following
|
||
- chinese
|
||
- command-translation
|
||
---
|
||
|
||
# darkhorse-code-instruct-1.5b
|
||
|
||
> **把一个微调过的 1.5B 小模型，做成编辑器里的「自然语言 → 私域命令」翻译器。**
|
||
> 输入一句中文口语，输出**一行严格 JSON**，不是聊天回复。
|
||
|
||
```
|
||
输入：关掉倒数第5个文件
|
||
输出：{"intent": "command", "cmd": "close -5"}
|
||
```
|
||
|
||
```json
|
||
{"intent": "command", "cmd": "del src/P05-es/pdf2es.py"} // 删除类
|
||
{"intent": "reject", "reply": "您没有权限！"} // 越权/不合法
|
||
{"intent": "chat", "reply": "你还是好好工作吧，房贷还清了吗？车贷还清了吗？"} // 非命令输入
|
||
```
|
||
|
||
本模型是 **Qwen2.5-1.5B-Instruct + LoRA（r=16）** 指令微调后**合并**（merged）得到的自包含权重，
|
||
不需要 `peft`、不需要 adapter，`transformers` / vLLM 直接加载即可。
|
||
|
||
---
|
||
|
||
## 1. 它解决什么问题
|
||
|
||
`darkhorse-code` 是一个编辑器项目，它有一套**私域命令语法**（`open project` / `close -3` /
|
||
`config add -r k=v` …），命令语法固定、可校验，但用户不想背。于是把「用户口语 → 一条标准命令」
|
||
这个窄任务交给一个 1.5B 小模型：**小、快、可完全本地跑，且输出必须能被程序解析**。
|
||
|
||
它不是通用聊天模型，**不会**回答知识问题、不会写代码、不会陪你聊天 ——
|
||
遇到非命令输入，它的正确行为是回一句 20 字以内的短回复（或一句固定的「劝退」话术）。
|
||
|
||
## 2. 输出契约（三种信封）
|
||
|
||
模型**只输出一行 JSON**，`intent` 决定信封形状：
|
||
|
||
| intent | 形状 | 含义 |
|
||
|---|---|---|
|
||
| `command` | `{"intent":"command","cmd":"<标准命令>"}` | 翻译成功，`cmd` 可直接执行 |
|
||
| `reject` | `{"intent":"reject","reply":"<拒绝原因>"}` | 命中硬性规则，如路径越权 |
|
||
| `chat` | `{"intent":"chat","reply":"<≤20字短回复>"}` | 不是私域命令 |
|
||
|
||
两条固定话术（评测按**逐字**判定）：
|
||
|
||
- 绝对路径出现在 `open file` / `new` / `del` / `rename` → `您没有权限！`
|
||
- 要求把运行目标存成全局配置 → `运行目标不能保存为全局`
|
||
- 闲聊超过 20 字说不完 → `你还是好好工作吧，房贷还清了吗？车贷还清了吗？`
|
||
|
||
## 3. 命令语法（模型学到的目标空间）
|
||
|
||
```
|
||
open project <绝对路径> | open file <相对路径>
|
||
close project|all|other|left|right|<序号> # 序号 0 起，负数从右往左，-1 是最后一个
|
||
config add|remove|update|get [-g|-p|-r] <key>=<value> # 未指定层级默认 -p
|
||
new file <相对路径> | new folder <相对路径> | new py|rs|md|c <名称>
|
||
del <相对路径> | run <名称>=<命令> | run del <名称>
|
||
rename <旧相对路径> <新相对路径>
|
||
project lang <语言> <绝对路径> | project delete <绝对路径> | project migrate
|
||
project edit "<路径>" "<名称>" <语言>
|
||
```
|
||
|
||
语言取值：`unknown/mix/java/c/python/rust/web/golang/document/kotlin`（中文表达做了映射：前端→web、Go→golang、文档→document…）。
|
||
|
||
## 4. 快速开始（transformers）
|
||
|
||
⚠️ **两条铁律，违反任一条效果都会明显掉：**
|
||
|
||
1. **必须使用本模型内置的 system prompt**（下面 `SYSTEM_PROMPT` 原文，逐字），
|
||
模型是在这份 prompt 下微调的；换 prompt = 训练/推理不一致。
|
||
2. **必须走模型自带的 chat template**（本仓库的 `chat_template.jinja`），
|
||
`tokenizer.apply_chat_template` 会自动读到它。
|
||
|
||
```python
|
||
import json
|
||
from transformers import AutoModelForCausalLM, AutoTokenizer
|
||
|
||
MODEL = "darkhorse-code-instruct-1.5b" # 换成你的 ModelScope 仓库 id
|
||
tok = AutoTokenizer.from_pretrained(MODEL)
|
||
model = AutoModelForCausalLM.from_pretrained(MODEL, torch_dtype="bfloat16", device_map="auto")
|
||
|
||
SYSTEM_PROMPT = """你是 darkhorse-code 编辑器的命令翻译器。把用户的话翻译成一条标准命令，只输出一行 JSON。
|
||
|
||
命令语法：
|
||
open project <绝对路径> | open file <相对路径>
|
||
close project|all|other|left|right|<序号>
|
||
close 的序号从 0 开始，负数从右往左，-1 是最后一个
|
||
config add|remove|update|get [-g|-p|-r] <key>=<value>，未指定层级默认 -p
|
||
new file <相对路径> | new folder <相对路径> | new py|rs|md|c <名称>
|
||
del <相对路径> | run <名称>=<命令> | run del <名称>
|
||
rename <旧相对路径> <新相对路径>
|
||
project lang <语言> <绝对路径> | project delete <绝对路径> | project migrate
|
||
project edit "<路径>" "<名称>" <语言>
|
||
|
||
规则：
|
||
1. 语言取值 unknown/mix/java/c/python/rust/web/golang/document/kotlin；中文表达要映射：Python→python、Go→golang、前端→web、文档→document、混合→mix、未知→unknown。
|
||
2. 绝对路径（以 / 或 C:/ D:/ 开头）只允许用在 open project、project lang/edit/delete 和 config 的值里；出现在 open file、new、del、rename 时一律拒绝，reply 固定为「您没有权限！」。
|
||
3. 路径里的正斜杠输出一律转成反斜杠。
|
||
4. 运行目标只能存项目配置，不能存全局；用户要求存全局时 reply 固定为「运行目标不能保存为全局」。
|
||
5. config 的值含空格时用双引号包裹。上下文给出已有运行目标时，新增运行目标索引 = 最大索引 + 1。
|
||
6. 不是私域命令的输入（闲聊、问知识、要你写文档）用 chat：reply 不超过 20 字；一句话说不完 20 字时 reply 固定为「你还是好好工作吧，房贷还清了吗？车贷还清了吗？」。
|
||
7. 同义命令输出规范形式：删除类写 del，关闭其他文件写 close other，重命名写 rename，新建目录写 new folder，run 的删除写 run del。
|
||
|
||
输出格式（只输出一行 JSON，不要解释、不要代码块）：
|
||
{"intent":"command","cmd":"<标准命令>"}
|
||
{"intent":"reject","reply":"<拒绝原因>"}
|
||
{"intent":"chat","reply":"<短回复>"}"""
|
||
|
||
|
||
def translate(text: str, context: str | None = None) -> dict:
|
||
# 上下文按训练时的约定另起一行：'[上下文] <内容>'
|
||
user = f"[上下文] {context}\n{text}" if context else text
|
||
msgs = [{"role": "system", "content": SYSTEM_PROMPT},
|
||
{"role": "user", "content": user}]
|
||
prompt = tok.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True)
|
||
ids = tok(prompt, return_tensors="pt", add_special_tokens=False).to(model.device)
|
||
out = model.generate(**ids, max_new_tokens=128, do_sample=False, # 贪心，别采样
|
||
pad_token_id=tok.pad_token_id or tok.eos_token_id)
|
||
raw = tok.decode(out[0][ids["input_ids"].shape[1]:], skip_special_tokens=True).strip()
|
||
return json.loads(raw) # 建议外面再包一层 try：小模型偶尔会多写一句解释
|
||
|
||
|
||
print(translate("把倒数第三个文件关掉"))
|
||
# {'intent': 'command', 'cmd': 'close -3'}
|
||
print(translate("加一个运行目标 测试=pytest -q", context="当前项目: D:/Projects/demo"))
|
||
# {'intent': 'command', 'cmd': 'run 测试=pytest -q'}
|
||
```
|
||
|
||
## 5. vLLM 部署（推荐，OpenAI 兼容）
|
||
|
||
8 GB 显存（如 RTX 5060 Laptop）即可跑 bf16：
|
||
|
||
```bash
|
||
vllm serve ./qwen2.5-1.5b-cmd-merged \
|
||
--served-model-name darkhorse-code-instruct \
|
||
--chat-template ./qwen2.5-1.5b-cmd-merged/chat_template.jinja \
|
||
--dtype bfloat16 --max-model-len 32768 \
|
||
--gpu-memory-utilization 0.85 --max-num-seqs 32 \
|
||
--enable-prefix-caching --port 8001
|
||
```
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8001/v1/chat/completions -H "Content-Type: application/json" -d '{
|
||
"model": "darkhorse-code-instruct",
|
||
"messages": [
|
||
{"role": "system", "content": "<上面那份 SYSTEM_PROMPT 原文>"},
|
||
{"role": "user", "content": "关掉倒数第5个文件"}
|
||
],
|
||
"temperature": 0, "max_tokens": 128
|
||
}'
|
||
```
|
||
|
||
要点：
|
||
|
||
- `temperature=0`（训练与评测都是贪心解码）；**不要**用 `generation_config.json` 里的默认采样参数。
|
||
- 请求里的 `system` 必须是上面那份原文；本项目服务端做薄封装时会把 system 强制替换成它。
|
||
- `choices[0].message.content` 是**契约 JSON 字符串**，调用方需要 `json.loads`。
|
||
- `--enable-prefix-caching` 对这类场景收益明显：所有请求共享同一份 553 token 的 system prompt 前缀。
|
||
- 需要「输出结构绝对合法」时，可以上受约束解码（JSON Schema 限死三种信封），
|
||
代价是采样空间被约束，个别内容可能与贪心输出不同。
|
||
|
||
### 实测性能（RTX 5060 Laptop 8G / sm_120，bf16）
|
||
|
||
同一批 15 条真实指令压测，`--max-model-len 32768 --max-num-seqs 32 --enable-prefix-caching`：
|
||
|
||
| 并发 | 请求吞吐 | 生成吞吐 | 延迟 p50 | 延迟 p95 |
|
||
|---|---|---|---|---|
|
||
| 1 | 3.6 req/s | 72 tok/s | 251 ms | 389 ms |
|
||
| 8 | 23.0 req/s | 469 tok/s | 278 ms | 425 ms |
|
||
| 32 | **49.4 req/s** | **1002 tok/s** | 337 ms | 480 ms |
|
||
|
||
流式 TTFT（并发 1）**87 ms**；显存占用：权重 3.1 G + KV cache 3.46 GiB（129,680 token ⇒ 32K 上下文可并发 3.96 路）。
|
||
参考：同一模型用 CPU + transformers 逐条生成是 **4.1–6.4 s/条**（约 0.2 req/s）。
|
||
|
||
### 在 WSL2 上部署的三个额外环境变量
|
||
|
||
vLLM 官方只发 Linux 轮子，Windows 用户通常跑在 WSL2 里；此时还需要：
|
||
|
||
```bash
|
||
# 1) V2 Model Runner 需要 pinned memory/UVA，而 vLLM 在 WSL2 上默认关掉 pin memory
|
||
export VLLM_WSL2_ENABLE_PIN_MEMORY=1
|
||
# 2) WSL 里若没有 gcc，Triton 运行时编译 kernel launcher 会报 "Failed to find C compiler"
|
||
# 可装 gcc（sudo apt-get install -y gcc g++），或用一个 zig cc 包装脚本当 CC
|
||
export CC=/path/to/your/c-compiler
|
||
# 3) 默认的 FlashInfer 采样器在缺 cubin 时会 JIT（需要 nvcc）；无 CUDA toolkit 时关掉它
|
||
export VLLM_USE_FLASHINFER_SAMPLER=0
|
||
```
|
||
|
||
另外 WSL2 无 CUDA toolkit 时建议 `--compilation-config '{"mode":0}'`（跳过 torch.compile，启动更快、不需要 C++ 编译器）。
|
||
|
||
## 6. 评测
|
||
|
||
评测集 **131 条**，全部**未出现在训练集模板**中的说法（含 27 条刻意构造的硬样本）：
|
||
中文序数词+负索引、口语化包装（「帮我/麻烦/能不能」）、上下文注入（`[上下文] 当前项目: …`）、
|
||
同义命令归一（删除/删掉/移除 → `del`）、绝对路径拒绝、运行目标索引推断…
|
||
|
||
| 指标 | 基座 Qwen2.5-1.5B-Instruct | **本模型（LoRA 微调后）** |
|
||
|---|---|---|
|
||
| 输出是合法 JSON | 131/131 = 100% | **131/131 = 100%** |
|
||
| 与标准命令**完全一致**（exact） | 39/131 = 29.8% | **122/131 = 93.1%** |
|
||
|
||
> 基座 JSON 合法率也是 100%，是因为语法和输出格式就写在 system prompt 里 ——
|
||
> 但「知道语法」≠「会用语法」：55 个命令族里有 39 个族的准确率发生变化，
|
||
> 基座在序号、配置、闲聊、拒绝这些地方大面积翻车。
|
||
|
||
几族的对比（体现微调到底学到了什么）：
|
||
|
||
| 命令族 | 基座 | 本模型 | 说明 |
|
||
|---|---|---|---|
|
||
| `close_index_neg`（倒数第 N 个） | 0/7 | **7/7** | 中文序数词 → 负索引 |
|
||
| `del`（删除/删掉/移除归一） | 5/9 | **9/9** | 同义命令规范形式 |
|
||
| `new_typed`（`new py/rs/md/c` 省后缀） | 0/4 | **4/4** | 类型子命令 |
|
||
| `run_add_ctx`（上下文推索引） | 0/5 | **5/5** | `max+1` 索引推断 |
|
||
| `reject_abs_dir` / `reject_abs_file` | 0/4 / 0/3 | **4/4 / 3/3** | 固定拒绝话术 |
|
||
| `open_project_fwd`（正斜杠归一） | 0/3 | **3/3** | `/` → `\` |
|
||
| `chat_long`（超 20 字固定话术） | 0/3 | **3/3** | 逐字背下话术 |
|
||
| `config_*`（add/get/update/remove） | 0/1~0/3 | **多数转正** | 仍是最弱的一族，见局限 |
|
||
|
||
**未满分的族（诚实列出，共 8 个）**：`config_get` 2/3、`config_remove` 1/3、
|
||
`hard/config` 2/3、`hard/close_index` 1/2、`hard/open_project` 1/2、`hard/reject_abs` 1/2、
|
||
`hard/reject_run_global` 0/1、`chat_short` 0/1。
|
||
典型错误是**配置层级判断**：用户说「去掉配置项 X」时，模型输出 `config remove -p X`，
|
||
而标准答案是 `config remove -r X`（这类「默认层级到底该取谁」的语义在数据里信号不够强）。
|
||
|
||
## 7. 输入输出示例（**真实推理输出**，取自上述评测集）
|
||
|
||
```
|
||
输入：关掉倒数第5个文件
|
||
输出：{"intent": "command", "cmd": "close -5"}
|
||
|
||
输入：打开 C:/Users/yujia/PycharmProjects/ai-notes
|
||
输出：{"intent": "command", "cmd": "open project C:\\Users\\yujia\\PycharmProjects\\ai-notes"}
|
||
（正斜杠已按规则归一为反斜杠）
|
||
|
||
输入：删除 C:/Users/yujia/PycharmProjects/tmf/src/utils.py
|
||
输出：{"intent": "reject", "reply": "您没有权限！"}
|
||
（绝对路径出现在 del 上 → 固定拒绝）
|
||
|
||
输入：[上下文] 已有运行目标: target3
|
||
加个运行目标 测试=.venv\Scripts\python.exe -m uvicorn app:api --port 8000
|
||
输出：{"intent": "command", "cmd": "run 测试=.venv\\Scripts\\python.exe -m uvicorn app:api --port 8000"}
|
||
|
||
输入：把 darkhorse.code.editor.tab_size 设置成 4，存到运行时
|
||
输出：{"intent": "command", "cmd": "config add -r darkhorse.code.editor.tab_size=4"}
|
||
|
||
输入：帮我建一个 rust 的模块，叫 order_service
|
||
输出：{"intent": "command", "cmd": "new rs order_service"}
|
||
|
||
输入：D:\Projects\Python\Code-Rag 是Kotlin项目
|
||
输出：{"intent": "command", "cmd": "project lang kotlin D:\\Projects\\Python\\Code-Rag"}
|
||
|
||
输入：你觉得我该不该辞职去创业，帮我分析一下利弊
|
||
输出：{"intent": "chat", "reply": "你还是好好工作吧，房贷还清了吗？车贷还清了吗？"}
|
||
```
|
||
|
||
## 8. 训练细节
|
||
|
||
| 项 | 取值 |
|
||
|---|---|
|
||
| 基座 | `Qwen/Qwen2.5-1.5B-Instruct` |
|
||
| 微调方式 | LoRA（`r=16`、`alpha=32`、`dropout=0.05`），训练后**合并**成自包含权重 |
|
||
| 可训练参数 | 约 1.18%（其余冻结） |
|
||
| 训练数据 | **1638 条**（模板 + 槽位合成，`--seed 42` 完全可复现，不用 LLM 生成） |
|
||
| 超参 | `lr=2e-4`、`warmup_ratio=0.03`、2 epoch、`max_len=704`、`micro_bs=1` × `grad_accum=8` → 410 步 |
|
||
| 耗时 / 显存 | 45.1 分钟 / 峰值 **7.68 GB**（单卡 8 GB 笔记本 GPU） |
|
||
| loss | train 0.6818 → 0.0079（末轮均值 0.0319）；eval 0.039 → 0.0092 |
|
||
| 精度 | bf16 |
|
||
|
||
**数据为什么是合成的**：这个任务要学的是「**照抄**」而不是「记住」—— 命令里大量是路径、命令串、
|
||
文件名。生成器把它们做成随机槽位，模型必须学会把输入里的路径原样搬进输出，而不是背样本；
|
||
同时保证可复现、零 API 成本、不会把外部 LLM 的错误学进去。
|
||
|
||
**三个刻意设计的难点**：① 约 15% 样本带上下文行，既要会用上下文补全、也要会忽略无关上下文；
|
||
② 随机加「帮我/麻烦/能不能/顺手」前缀与「吧/，谢谢/呀」后缀，放大表达多样性；
|
||
③ 27 条硬样本**只进评测集**，用来量真实泛化而不是量记忆。
|
||
|
||
## 9. 已知局限（请务必先读）
|
||
|
||
1. **只懂 darkhorse-code 的命令语**。换个 CLI/编辑器的命令体系，必须重新造数据微调。
|
||
2. **不是聊天模型**：闲聊会被压成 ≤20 字短回复，甚至回那句固定的「劝退」话术 —— 这是设计目标，不是 bug。
|
||
3. **`config` 族最弱**（见 §6）：配置层级（`-g/-p/-r`）的默认值判断会出错，接入方应对
|
||
`config` 类输出做二次校验（层级缺失时按自己的业务规则补默认值）。
|
||
4. **输出偶尔会被解析层救回来**：小模型可能把 JSON 包在 ```json 代码块里、或路径里写单反斜杠
|
||
（非法 JSON 转义）。建议接入方保留「抠 JSON + 修非法转义」的解析兜底，而不是直接 `json.loads`。
|
||
5. **上下文格式是约定**：必须写成 `[上下文] <内容>` 并**另起一行**再接用户原话，
|
||
这是训练时的格式，别自由发挥。
|
||
6. **1.5B 的常识/推理上限**：超出命令翻译的语义理解（比如反讽、多轮澄清）不要指望它。
|
||
|
||
## 10. 文件说明
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `model.safetensors` | bf16 合并权重（约 2.9 GB），自包含、无需 adapter |
|
||
| `chat_template.jinja` | **模型配套的 chat template**，请务必用它（vLLM `--chat-template` 指向它） |
|
||
| `config.json` / `generation_config.json` | Qwen2 结构（28 层、2 KV head、`max_position_embeddings=32768`） |
|
||
| `tokenizer.json` / `tokenizer_config.json` / `vocab.json` / `merges.txt` / `added_tokens.json` | tokenizer 全套 |
|
||
| `configuration.json` | ModelScope 标记文件 |
|
||
|
||
## 11. 许可与致谢
|
||
|
||
- 本模型以 **Apache-2.0** 许可发布，与基座 `Qwen/Qwen2.5-1.5B-Instruct` 一致；
|
||
使用前请同时遵守基座模型的许可条款。
|
||
- 感谢 Qwen 团队开源的 Qwen2.5 系列。
|
||
- 训练所用数据为由模板与槽位**程序生成**的合成数据，不含任何真实用户数据或第三方隐私内容。
|