在 Windows 上面部署 StartLux

本文档记录在 Windows + RTX 4060（8GB 显存）上完整部署 StartLux-Decision-v1.1-4B-AutoThink 决策模型的全过程，含每一步踩过的坑与解法，命令均可直接复制执行。

最终架构为官方推荐的 GGUF + llama.cpp 路线：

llama-server (加载 GGUF Q8_0 权重, 端口 8081)  ←  负责推理
        ↑ HTTP
startlux-decide (读 BF16 文件夹的 tokenizer/config, 端口 8090)  ←  决策引擎
        ↑ HTTP
curl / 客户端

---

一、环境与配置信息

以下为本机实测、验证可跑通的软硬件配置，可作为部署前的基线参考。

硬件与驱动（Windows 侧）

项目	配置
GPU	NVIDIA GeForce RTX 4060（笔记本版）
显存	8188 MiB（约 8 GB）
功耗	100 W（Cap）
NVIDIA 驱动	610.57.01
CUDA UMD	13.3
KMD	610.88
WSL 与软件环境
组件	版本 / 路径
---	---
WSL	3.0.3（wsl --update 后）
发行版	Ubuntu 24.04 LTS（noble），用户名 rog
Python	3.12（Ubuntu 24.04 默认）
虚拟环境	~/slenv
vLLM	0.31.0
startlux-decide	1.1.0
llama.cpp	b11809（ubuntu-x64 预编译包）
仓库位置	D:\model\StartLux\StartLux-Decision（WSL 内为 /mnt/d/model/StartLux/StartLux-Decision）
llama.cpp 位置	D:\model\StartLux\llama-b11809
模型与端口
项目	说明
---	---
GGUF 权重（推理用）	StartLux-Decision-v1.1-4B-AutoThink-Q8_0.gguf，约 4.2 GB
BF16 文件夹（tokenizer/config 用）	models/StartLux-Decision-v1.1-4B-AutoThink，约 9 GB
llama-server 端口	8081
决策引擎端口	8090
上下文长度	16384 tokens（8GB 显存下的稳妥值）

---

二、安装 WSL2 与 Ubuntu 24.04

以管理员身份打开 PowerShell：

# 查看现有发行版（初始为空）
wsl -l -v
# 更新 WSL 组件
wsl --update        # 本机更新至 3.0.3
# 安装 Ubuntu 24.04
wsl --install -d Ubuntu-24.04

首次启动会提示创建 Unix 用户（本机为 rog）并设置密码。

⚠️ 坑 1：wsl --install -d Ubuntu 超时/连不上

需要科学上网

⚠️ 坑 2：启动时提示 "检测到 localhost 代理配置，但未镜像到 WSL"

NAT 模式下 WSL 无法使用 Windows 侧的 localhost 代理。若 Windows 走代理上网，WSL 内 apt/pip/下载可能极慢或失败。解决方法是开启镜像网络模式 ：在 C:\Users\<用户名>\ 下新建 .wslconfig：

[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true

然后在 PowerShell 执行 wsl --shutdown，重新进入 WSL 生效。镜像模式会让 WSL 与 Windows 共享网络栈和代理配置。

三、安装基础依赖（WSL Ubuntu 内）

Ubuntu 24.04（noble）官方源已不提供 python3.10，默认 Python 即 3.12，直接安装不带版本号后缀的包：

sudo apt update
sudo apt install -y python3-venv git

⚠️ 坑 3：Unable to locate package python3.10-venv ------ 旧教程针对 Ubuntu 22.04 的写法，在 noble 上请去掉 3.10。

---

四、创建虚拟环境并安装 startlux-decide

# 创建并激活虚拟环境
python3 -m venv ~/slenv
source ~/slenv/bin/activate
# 进入仓库（D 盘）
cd /mnt/d/model/StartLux/StartLux-Decision
# 安装（含 vllm extra）
pip install -e ".[vllm]"

安装会拉取 vLLM、torch、flash-linear-attention 等依赖，下载量约 5--8 GB，耐心等待。每次重开 WSL 终端后需重新执行 source ~/slenv/bin/activate（提示符前出现 (slenv) 即已激活）。

五、下载模型：GGUF 路线（关键决策）

为什么不用 vLLM 直接跑 BF16 ：BF16 权重约 9 GB > 4060 的 8 GB 显存，vLLM 引擎初始化必然 CUDA out of memory（实测在 warmup 后崩于 Engine core initialization failed）。

为什么不用 FP8 ：HF 上不存在 StartLux-Decision-v1.1-4B-AutoThink-FP8 仓库（实测报 Model not found）。

官方量化方案是 GGUF ，提供 Q8_0（约 4.2 GB，精度损失最小）和 Q4_K_M（约 2.5 GB，最大损失约 3.8 DecisionPivot 点）。8GB 显存推荐 Q8_0 + 压缩上下文 。

在仓库目录内下载（注意 --local-dir 指向仓库内的 models/）：

hf download startlux-models/StartLux-Decision-v1.1-4B-AutoThink-GGUF \
  StartLux-Decision-v1.1-4B-AutoThink-Q8_0.gguf \
  --local-dir models/StartLux-Decision-v1.1-4B-AutoThink-GGUF

下载过程中出现的 Hint: The hf-cli skill is not installed 是给 AI 编码插件的提示，No local file found. Retrying.. 是断点续传日志，均非错误 ，出现文件路径返回即成功。多模态文件 mmproj-...-F16.gguf（672 MB）在不用图像输入时可不下。

⚠️ 坑 4：模型路径定位。仓库内有 models/ 子目录，GGUF 和此前下载的 BF16 文件夹都在其中（find /mnt/d/model -name decision_config.json 可确认）。BF16 文件夹不能删 ------决策引擎仍需从中读取 tokenizer、config.json、decision_config.json。

---

六、安装 llama.cpp 并补齐运行库

从 llama.cpp releases 下载 Ubuntu 预编译包并解压到 D:\model\StartLux\（本机为 llama-b11819）。

⚠️ 坑 5：启动报 libgomp.so.1: cannot open shared object file ------ 最小化 WSL Ubuntu 缺 OpenMP 运行库，补齐：

sudo apt install -y libgomp1 libcurl4t64 libatomic1

验证依赖完整（无输出即 OK）：

ldd /mnt/d/model/StartLux/llama-b11809/llama-server | grep "not found"

性能提示：官方 ubuntu-x64 包为 CPU 版（ldd | grep -i cuda 无输出），跑 4B Q8 约 5--15 token/s，功能完全可用 。若需 GPU 加速（80+ token/s），改下载带 CUDA 的包或源码编译 -DGGML_CUDA=ON，或直接在 Windows 侧用 bin-win-cuda-12.4-x64 包跑 llama-server。

---

七、启动服务（两个终端）

终端 1 ------ llama-server（先启动，保持窗口不关）：

cd /mnt/d/model/StartLux/llama-b11819
LD_LIBRARY_PATH=$PWD:$HOME/slenv/lib/python3.12/site-packages/nvidia/cu13/lib \
./llama-server \
  -m /mnt/d/model/StartLux/StartLux-Decision/models/StartLux-Decision-v1.1-4B-AutoThink-GGUF/StartLux-Decision-v1.1-4B-AutoThink-Q8_0.gguf \
  -ngl 99 -c 32768 -fa on --cache-type-k q8_0 --cache-type-v q8_0 --port 8081 --parallel 8

成功标志：日志末尾出现 server is listening on http://127.0.0.1:8081。

终端 2 ------ startlux-decide 决策引擎（后启动）：

cd /mnt/d/model/StartLux/StartLux-Decision
source ~/slenv/bin/activate
startlux-decide serve --model models/StartLux-Decision-v1.1-4B-AutoThink \
  --backend llamacpp --llamacpp-url http://127.0.0.1:8081 --port 8090

注意 --model 指向 BF16 文件夹 （供决策引擎读配置），而非 GGUF 文件。若仍报 no decision_config.json，先用 ls 核对模型实际所在目录再修正路径。

八、验证部署

curl -s localhost:8090/v1/systemone -H 'Content-Type: application/json' -d '{
  "state": {"ticket": "I was charged twice for order #4411."},
  "questions": {
    "urgent": {"type": "noul", "instructions": "Should this ticket be answered today?"}
  }
}'

期望返回类似：

{"answers": {"urgent": {"type": "noul", "noul": 0.6525096546249004}},
 "usage": {"input_tokens": 77, "output_tokens": 0},
 "model": "StartLux-Decision-v1.1-4B-AutoThink"}

noul 值即决策概率（0.65 ≈ 65% 倾向"是"）。output_tokens: 0 是正常现象------此类问题不生成文本，一次前向传播直接读概率。

九、常见错误速查表

报错 / 现象	原因	解法
Unable to locate package python3.10-venv	noble 无 3.10 包	改用 python3-venv
wsl --install -d Ubuntu 超时	GitHub 清单拉取被墙	改 wsl --install -d Ubuntu-24.04
localhost 代理未镜像提示	NAT 模式限制	.wslconfig 开镜像网络 + wsl --shutdown
no decision_config.json	--model 路径指错	模型在仓库内 models/，用相对路径或完整路径
vLLM Engine core initialization failed	BF16 9GB > 8GB 显存 OOM	弃 vLLM，走 GGUF + llama.cpp
Model '...FP8' not found	FP8 仓库不存在	用官方 GGUF 仓库（Q8_0 / Q4_K_M）
libgomp.so.1: cannot open shared object file	缺 OpenMP 运行库	apt install libgomp1 libcurl4t64 libatomic1
llama-server 启动即 OOM	KV cache 超显存	上下文降至 -c 8192，或换 Q4_K_M
startlux-decide: command not found	venv 未激活	source ~/slenv/bin/activate

---

十、日常重启流程

关机或关闭终端后，按顺序恢复服务：

# 1. 进入 WSL
wsl
# 2. 终端 1：启动 llama-server（第 7 节命令）
cd /mnt/d/model/StartLux/llama-b11819
LD_LIBRARY_PATH=$PWD:$HOME/slenv/lib/python3.12/site-packages/nvidia/cu13/lib \
./llama-server \
  -m /mnt/d/model/StartLux/StartLux-Decision/models/StartLux-Decision-v1.1-4B-AutoThink-GGUF/StartLux-Decision-v1.1-4B-AutoThink-Q8_0.gguf \
  -ngl 99 -c 32768 -fa on --cache-type-k q8_0 --cache-type-v q8_0 --port 8081 --parallel 8

# 3. 终端 2：激活 venv 后启动决策引擎
cd /mnt/d/model/StartLux/StartLux-Decision
source ~/slenv/bin/activate
startlux-decide serve --model models/StartLux-Decision-v1.1-4B-AutoThink \
  --backend llamacpp --llamacpp-url http://127.0.0.1:8081 --port 8090

随后即可通过 http://localhost:8090 调用决策接口。