部署 FlashRec

默认单进程部署。不要引入张量并行、多卡、Docker 编排或鉴权网关，除非用户明确要求。 完整旋钮见 docs/configuration.zh-CN.md。目录与评测分别走 sid-catalog、recif-eval。

前置

• Linux + NVIDIA GPU + CUDA 12 工具链；Python ≥ 3.10
• HuggingFace 格式 checkpoint（config.json + tokenizer + safetensors）
• 当前只支持 Qwen3 dense（0.6B–14B、OneRec-1.7B、同架构 GenRec）。MoE / 其他架构走 add-model
• 32 GB 显存下 FP8 大约到 14B

先确认环境：

python -m flashrec.check_env

安装

pip install -e .
# 或 wheel：
bash scripts/build_wheel.sh && pip install dist/flashrec-*.whl

启动服务

默认入口是 scripts/serve.sh（会设 PYTHONPATH 并展开调度环境变量）。 可调参数模板：scripts/serve.env.example（复制为 scripts/serve.env 或设 SERVE_ENV）。

服务配置是 MODEL_PATH + SID_VOCAB_FILE。引擎从 tokenizer 推断 SID 布局 （<s_a_0> codebook + <|sid_begin|> / <|sid_end|>）。不设 catalog 时做全词表 无约束解码（无 trie），只适合冒烟。

SID_VOCAB_FILE=data/catalogs/sid2pid_beamrec_l4.json \
MODEL_PATH=/path/to/model bash scripts/serve.sh
# 等价：
flashrec --serve --model-path /path/to/model --port 8000 \
  --sid-vocab-file data/catalogs/sid2pid_beamrec_l4.json

常用覆盖：HOST、PORT、CUDA_VISIBLE_DEVICES、QUANTIZATION、KV_CACHE_DTYPE、 MEM_FRACTION_STATIC、CUDA_GRAPH_MAX_BS、BATCH_SLOTS、BEAM_WIDTH、 EXTRA_SERVER_ARGS。

OneRec-1.7B（文档中的服务配置）

先构建 catalog（见 sid-catalog），再：

CUDA_VISIBLE_DEVICES=0 \
MODEL_PATH=/path/to/OneRec-1.7B PORT=8000 HOST=127.0.0.1 \
QUANTIZATION=fp8 KV_CACHE_DTYPE=fp8_e4m3 \
CUDA_GRAPH_MAX_BS=800 BATCH_SLOTS=800 \
SID_VOCAB_FILE=data/catalogs/sid2pid_beamrec_l4.json \
BEAM_WIDTH=50 \
  bash scripts/serve.sh

tokenizer 不用 <s_a_0> / <|sid_begin|> 约定时，再设 SID=START:END/SIZE,... 覆盖推断。

宽 beam（n = 512 / n = 1000）

默认槽位 800，一波只能进一个 512-beam 请求，且纯 LPM 可能饿死短 prompt。 n = 1000 用同一套 4096 槽位（约 4 路并发）：

CUDA_GRAPH_MAX_BS=4096 BATCH_SLOTS=4096 LPM_AGING_MS=150 \
  BEAM_WIDTH=512 MODEL_PATH=/path/to/model \
  SID_VOCAB_FILE=data/catalogs/sid2pid_beamrec_l4.json \
  bash scripts/serve.sh

--beam-width 决定 fused-expand 的捕获宽度；graph 尺寸会扩成 k × n。 单实例只服务一种主力 beam 宽度。

就绪检查与请求

curl -sf http://127.0.0.1:8000/health
# {"status":"ok"}

curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"..."}],"n":50,"max_tokens":5,"temperature":0}'

• n：该请求 beam 宽度（覆盖服务端 --beam-width）
• temperature=0：确定性 top-k；>0 为 Gumbel top-k，噪声只用于排序，返回的 sglext.sequence_score 不含噪声
• 离线单次：flashrec --model-path ... --sid-vocab-file ... --prompt "..." --beam-width 50 --max-tokens 5

Profiling（与 sglang.bench_serving --profile 对齐）：POST /start_profile、POST /stop_profile。 不要在 HTTP 线程上包 torch.profiler。

精度与显存

目标	设置
默认生产	--quantization fp8（W8A8 per-channel）+ --kv-cache-dtype fp8_e4m3
纯 BF16	--quantization 传非 fp8 的值
预量化 FP8 checkpoint	带 weight_scale 即可加载
OOM	降 --mem-fraction-static，或改小 --cuda-graph-max-bs / --batch-slots / --beam-width

FP8 在小模型窄 beam 上不一定更快，主要省权重与 KV 显存。 OneRec-1.7B 等 BF16 训练 的 checkpoint 走加载时量化时，相对 HuggingFace 的 beam 重叠会下降，这不是框架问题；生产建议用 FP8 训练（或带 weight_scale 的预量化）权重。对照见 docs/baselines.zh-CN.md。

安全

服务无鉴权，默认绑 127.0.0.1。只在可信网或反向代理后才设 HOST=0.0.0.0。

故障排查

1. python -m flashrec.check_env：CUDA / flashinfer / sgl-kernel / 驱动
2. /health 不通：看进程是否还在、端口、CUDA graph 捕获是否卡在启动
3. 非法 SID 或超长输出：确认 SID_VOCAB_FILE 对应该 checkpoint；启动日志应有 Inferred --sid ...。tokenizer 命名不同时才设 SID=
4. 宽 beam 吞吐不随并发上升：槽位不够（BATCH_SLOTS < n × 并发）
5. 新架构加载失败：当前 ModelEngine 写死 Qwen3ForCausalLM，见 add-model