CHAPTER 24
附录 B 旋钮表
四张表：引擎 CLI 旋钮 / 引擎环境变量 / 服务层配置 / 网关 config.json，加 supervisor 程序表。
"默认"列来自SSEStraBed/src/program/generate.cpp选项结构体（行号见附录 A.1.2）；
“生产值"列来自 2026-10-20 当场读的两条 lane 配置（Strata/strata-iq3_xxs-b.json、
deploy/engines/profiles/ssebed/strata-a.json，两条 lane 的args数组逐项完全相同）。
2026-10-21 复核：两条 lane 都已指向deploy/engines/profiles/ssebed/strata-{a,b}.json，
args仍逐项相同；--batch-groups两条都是 1（旧口径 B=2 已过期）。
密钥类字段一律只写"存在”，不写值。
B.1 引擎 CLI 旋钮（args 数组）
B.1.1 生产里显式设的
| 旋钮 | 引擎默认 | 生产值 | 作用 | 调错的症状 |
|---|---|---|---|---|
--pack |
— | ~/Strata-data/packs/iq3_xxs |
权重包目录（专家、profile、tokenizer 都从这里派生） | 起不来，strata 直接退出 |
--native / --ple-gguf |
— | IQ3_XXS 的两个分片（dense + PLE） | 常驻 GPU 的 dense 权重与 n-gram 嵌入 | 显存 OOM / PLE 缺失导致质量崩 |
--expert-profile |
— | Strata/data/expert-profile.bin |
专家路由画像（决定哪些专家常驻） | 命中率崩 → 落盘 → 解码掉到个位数 tok/s |
--expert-cache |
— | auto |
自适应专家缓存（GPU 剩余显存里放热专家） | 太小 → 频繁换入；太大 → 挤掉 KV |
--prefill |
— | auto |
prefill 分块大小（STRATA_PREFILL_AUTO_MAX 决定 auto 上限） |
块太大 → 单请求独占 GPU 更久（09 章） |
--spec |
0（:389） | 4 | 投机解码校验窗口 T（T≥2 才启用） | 关掉 → 解码速度掉；调大 → 校验预算涨（kVerifyMaxT=8 是硬上限） |
--spec-min-p |
— | 0.5 | 草稿接受概率门槛 | 调低 → 接受率低时白做草稿 |
--mtp |
— | ~/Strata-data/mtp/rt |
MTP 草稿层 GGUF（草稿由模型自己出） | 缺它 → serve 模式直接 return 2（:4501） |
--mtp-varlen |
关（2026-10-21 新增） | 两条 lane 都开 | 自适应验证窗口：按逐位置接受率 + 实测 step 曲线选 L（10 章 §10.3.1） | 不带它 = build 1 行为；带它但违反 L ≤ 上轮草稿深度+1 → 校验清零草稿、规划器自锁（报告 §5.4） |
STRATA_STEP_STATS（env） |
未设=不写 | ~/logs/step-stats-{a,b}.jsonl |
每窗口/每次 prefill 一行 JSONL，analyze_steps.py 消费 |
设了但盘满/误删 → 仅丢统计，不影响服务 |
--max-context |
— | 262144 | 会话总窗口（决定 KV 与各类显存） | 调大 → 显存/内存双爆；这是硬约束 1 |
--kv |
— | int8 |
KV 精度（fp16 / int8 / q4_0 / k8v4） | 降精度省显存但影响长上下文质量 |
--kv-resident |
— | 32768 | 常驻显存的 KV 行数 | 太小 → 长会话流式换入换出 |
--vision |
— | 开 | 启用图像（配合 strata-vision sidecar） |
关掉 → 图片请求失败 |
--conversation-cache-slots |
— | 20 | 停车槽数（12 章第四层） | 与 -mib 一起决定能停几条长会话 |
--conversation-cache-mib |
0（关，:440） | 8192 | 停车 RAM 预算 | 事故 2 的核心：254k 会话快照 4.7 GB → 装两三条就驱逐 |
--conversation-cache-min-free-mib |
2560（:442） | 未设（用默认） | 低于此空闲就不停车 | 调高 → 更保守、更少驱逐但更少复用 |
--vram-reserve-mib |
700（:365） | 1600 | 给驱动/其它留的显存 | 调小 → 链捕获失败 → chain_off 永久降级（10 章） |
--ple-io |
— | ram |
PLE 放主机 RAM（不放 SSD） | 换 ssd → 解码期随机读延迟 |
--pool-workers |
0 = 物理核减宿主（:284） | 13 | CPU 专家池线程数 | 事故 1：两实例各 24 worker 抢 32 核 → 9.3 tok/s；降 worker 无效、钉核才有效。13 已是上限：taskset 把 lane 钉在 16 核，13 worker + 宿主 = 14 线程已饱和（21.2 的否决记录） |
--batch |
0（关，:393） | 4 | serve 一次并行跑几条序列（并发上限在这里） | 调大 → 显存与 GMAX 压力；--batch 需要每个 stage 独占一张卡（:4966） |
--batch-mtp |
false（:400） | 开 | 批槽也跑 MTP 链（v1 只对 greedy 槽） | 失败会 falling back to one-token windows（:5846） |
--batch-groups |
1（:399） | 1 | 批分组 | 需要 layer split 且整除 --batch（:5867） |
B.1.2 生产里没设、因此吃默认值的（= 可调空间）
| 旋钮 | 默认（行号） | 含义 | 调它会发生什么 |
|---|---|---|---|
--prompt-cache |
6（:439） | 请求之间保留几个对话检查点，每个约 118 MB 主机 RAM | 调大 → 复用更多、RAM 更紧（现 176/216 GiB 悬顶） |
--prompt-cache-every |
16384（:444） | 每 16384 token 打一个检查点 | 事故 2 的第二环：被驱逐的会话只能靠检查点，密度 16384 → 只救回 16384，其余 ~238k 整段重读。改 4096 → RAM 涨约 4× |
--prompt-cache-root |
2048（:447） | 会话开头的"根"检查点密度 | 影响第一轮/短会话的复用 |
--layer-split |
未设（dual 布局不用） | 按层切到多卡（只配 --serve） |
split 布局用；与 --peer-device 互斥（:1945）；单卡 split 与停车互斥（:1604–1607） |
--peer-device |
-1（关，:327） | 把另一张卡当主从专家缓存层 | 与 --layer-split、--expert-cache-device1..3 互斥 → 对称共享专家池不可行（19 章已否决表） |
--pcie-frac |
-1 = 按包类型取默认（原生包 0.55）并实测 PCIe 修正（:413、:2064-2077） | 未设 | 未命中专家里由 GPU 经 PCIe 读的比例 |
--short-read |
64（:459；门在 :6547） |
未设 | 不超过 N 个 token 的段走解码窗口读，而不是批处理 prompt 路径（read_windows :6554） |
--api-monitor（serve 层，非引擎） |
关 | 每请求内容留存 | 见 B.3 |
TTFT 四旋钮（12 章 §12.7、19 章 P1）就是上面这张"没设"表里的三个 + 停车预算：
conversation-cache-mib8192→24000+、prompt-cache-every16384→4096、普道准入、组装预算封顶。
四个都只改配置不改代码，但都要重启那条 lane（6–13 分钟）。
B.1.3 编译期常量：不是旋钮，但决定天花板
这五个数字改不了（除非重编），但排查"为什么快不起来"时必须先看它们：
| 常量 | 值 | 位置 | 它卡住了什么 |
|---|---|---|---|
kStagingBlobs |
16 | include/strata/core/verify.hpp:357 |
一帧最多 16 个未命中专家走 PCIe 快档，第 17 个起全落 CPU（07 章 §7.12） |
kVerifyMaxT |
8 | include/strata/kernels/verify_kernels.hpp:28（iq_kernels.cu:1804 是它的注释引用） |
一帧总行数上限；L_max = min(4, 8/S) 的来源（10 章 §10.8） |
GMAX |
8 | src/kernels/cuda/s2_expert_grouped.cu:1360 |
每一专家组的条目上限，超出被 min(...,GMAX) 静默截断 |
MAXT |
8 | src/kernels/cpu/kq_avx2.cpp:43、include/strata/kernels/cpu/expert.hpp:169 |
CPU 池一次能处理的 token 数 |
dma_src[64] |
64 | src/core/expert_source.cpp:3384 |
单层 DMA 源指针数组 |
--batch 上限 |
2…kVerifyMaxT |
generate.cpp:2960-2961 |
槽数不能超过 8 |
这六个里，只有
kStagingBlobs是"加一点显存就能放宽"的（16→32 = +30 MB）。
其余都要连 kernel 模板一起改并重录 CUDA Graph（21.6）。
B.2 引擎 / 服务层环境变量
| 变量 | 谁读 | 作用 | 备注 |
|---|---|---|---|
STRATA_PREFILL_YIELD_CHUNKS |
引擎 generate.cpp:6688（legacy :6338） |
批量读提示词每段切成几块（0 = 不让出，即 prefill 独占） | 09 章"prefill 全局串行"的现成缓解旋钮 |
STRATA_PREFILL_YIELD_STEPS |
引擎 :6692（legacy :6342） |
每段之间让出多少个解码窗口 | 与上者配对；两者都在 --serve 路径生效 |
STRATA_ESCAPE_SPECIAL |
serve server.py:1260 |
设 0 关闭特殊 token 转义（事故 3 的开关） |
默认开；关掉会退回早停行为 |
STRATA_REQUEST_LINES |
serve :202, :365 |
每个完成请求在 stdout 打一行（从引擎日志摘要取） | 排障时有用 |
STRATA_BATCH_TRACE |
serve :297（_BTRACE） |
批窗口 trace 输出 | 调试批槽 |
STRATA_ALLOWED_HOSTS |
serve :1277, :3027 |
允许哪些 Host 名（DNS rebinding 防护） | 与配置 allowed_hosts 合并 |
STRATA_API_KEY |
serve :3249（--api-key 默认值） |
服务鉴权 key | 值不进书、不进 git |
STRATA_DEBUG |
引擎多处 | 打开 token 级 dump（事故 5 的 B 模式需要它才能进一步定位） | 输出量大 |
CUDA_VISIBLE_DEVICES / CUDA_DEVICE_ORDER |
serve child_env() :1161 |
按 cfg["gpu"] 收敛可见卡（PCI_BUS_ID 顺序，避免 nvidia-smi 编号与 CUDA 编号错位） |
由配置 gpu 决定，不要手改 |
LD_LIBRARY_PATH |
同上 | 从 lib_dirs 前置 CUDA 库路径 |
— |
HF_ENDPOINT |
supervisord environment= |
https://hf-mirror.com（公网不通） |
五个程序都带 |
TASKSET / ENGINE_NAME / CONFIG / CWD / PORT / PYTHON / SERVER_PY |
run-iq3_xxs-{a,b}.sh |
薄分发器的可覆盖变量（15 章 §15.3） | 覆盖 TASKSET 必须复查（红线 3） |
STRATA_PF_FUSED |
引擎 src/prefill/moe_fused.cu:428（requested()） |
设 1 让 prefill 的 MoE 走融合 int8 kernel（专家分组在 GPU 侧完成，不再每层 cudaStreamSynchronize） |
生产未设。本包类型全覆盖、cc 8.9 满足门槛，只差这个开关（09 章 §9.9）。改了要核对同 prompt 贪心输出一致 |
引擎内部 kernel 开关（STRATA_DP4A、STRATA_GR_V3、STRATA_ARGMAX_MULTI、STRATA_QSA_CLUSTER、STRATA_OLD_GROUPED …共 60+） |
引擎 kernel 层 | 逐 kernel 的实现选择与 parity 回退 | 不是运维旋钮：改它们等于改数值实现，必须过 src/kernels/*_parity.cpp 对照 |
B.3 服务层配置（lane 的 strata-*.json 非 args 字段）
| 键 | 生产值（A / B） | 作用 |
|---|---|---|
exe |
SSEStraBed/build/strata / Strata/build/strata |
引擎二进制 |
cwd |
SSEStraBed / Strata |
引擎工作目录 |
tokenizer |
~/Strata-data/packs/iq3_xxs/tokenizer |
serve 侧 tokenizer（转义用的 CONTROL 类就从这里取） |
model_name |
qwen3.8-flash-next-iq3_xxs |
上游模型名 |
log |
SSEStraBed/logs/strata-iq3_xxs-a.log / Strata/strata-iq3_xxs-b.log |
引擎明细日志（12 章取证源） |
lib_dirs |
/usr/local/cuda/{bin,lib64} |
CUDA 库 |
port / host |
8091 或 8092 / 127.0.0.1 |
只监听回环（只有 8080 对外） |
gpu |
0 / 1 | 可见卡 |
gpus_asked |
true | 显式请求过 GPU |
api_key |
存在（0600） | 引擎自身鉴权；值不进书 |
fit_max_tokens |
两条 lane 都为 true（2026-10-21 复核：ssebed 的 strata-b.json 此前缺这个键，现已补上） |
超窗时把 max_tokens 裁到剩余空间，而不是回 400（server.py:1754–1764）。缺它会静默改变超窗行为 —— 每次换 profile 都要复查 |
api_monitor |
未设（关） | 开则 /api/requests、/api-monitor 可用（server.py:2533, 2551）；有内存与隐私代价 |
vision.exe / mmproj / model / gpu / max_tokens: 1024 |
两条 lane 相同（Strata/engine/strata-vision + BF16 mmproj） |
图像编码 sidecar；单图 ≤1024 token 就是这里定的（14.9 实测 33 / 324 / 996） |
B.4 网关 rag-proxy/config.json（全部键，2026-10-20 当场读）
入口与路由
| 键 | 值 | 说明 |
|---|---|---|
listen_host / listen_port |
0.0.0.0 / 8080 |
唯一公网面 |
upstream |
http://127.0.0.1:8091 |
单上游口径（split 布局遗留） |
upstreams |
[8091, 8092] |
双 lane |
model_routes |
strata-a→8091、strata-b→8092、qwen3.8-flash→8092、qwen3.8-flash-fast→8091 |
按模型 ID 定通道 |
default_upstream |
http://127.0.0.1:8092 |
没登记的模型走普道 |
lane_labels |
8091=快道、8092=普道 | /concurrency 显示用 |
lane_poll_s |
2 | 通道状态轮询 |
| （无键）上游 failover | 2026-10-21 起内置 | 被路由到的 lane 连不上时，自动改投 upstreams 里另一条活着的 lane 重试一次；日志 改投，计数 upstream_failover（16 章 §16.4） |
api_key_file |
存在 | 客户端鉴权 key 文件；值不进书 |
窗口与计数（10-19 新增的一族）
| 键 | 值 | 说明 |
|---|---|---|
max_context |
262144 | 与引擎一致（中继侧是 256000，待对齐） |
ctx_slack |
8 | 计数余量 |
gen_reserve_default / gen_reserve_max |
8192 / 32768 | 给生成预留 |
chars_per_token |
2.5 | 粗估基准（精确计数走 count_tokens） |
tok_per_char_cjk / _digit / _other |
1.05 / 1.05 / 0.70 | 上界估算系数；注释自证实测英文 0.19 → 英文高估 ~3.3×（事故 6） |
msg_overhead_tokens |
8 | 每条消息的框架开销 |
image_tokens |
1024 | 一张图按 1024 计（count_tokens 只数 1 个 pad） |
clamp_margin_tokens / clamp_margin_div |
512 / 64 | clamp_max_tokens 的安全边 |
retry_on_overfit |
true | 引擎仍报 400 时按引擎给的余量压 max_tokens 重试一次（room<1 已不再盲重试） |
thinking_budget_guard / answer_reserve_tokens / answer_reserve_div |
true / 4096 / 3 | 思考预算守卫 |
count_timeout_s |
10 | 调 serve count_tokens 的超时（失败则降级为估算） |
debug |
false | 打开 dbg() |
检索组装（当前 rag_enabled=false，全部处于休眠）
| 键 | 值 |
|---|---|
rag_enabled |
false（纯透传，有效上下文回到引擎原生 256K） |
embed_url / embed_model / rerank_url |
集群内 bge-m3 / bge-reranker 端点 |
recent_window_tokens |
65536 |
query_max_tokens / memory_min_tokens |
2048 / 4096 |
chunk_tokens / chunk_overlap_tokens |
768 / 128 |
structure_chunking / context_expand_ratio |
true / 0.25 |
block_drift_rebuild / block_relevance_min / block_check_docs / block_check_chars |
true / 0.3 / 128 / 600 |
retrieve_candidates / rerank_candidates / mmr_lambda |
200 / 200 / 0.7 |
score_w_rerank / score_w_recency / score_w_role |
0.55 / 0.3 / 0.15 |
assembly_ttl_s / rerank_cache_ttl_s / session_ttl_s |
10800 / 10800 / 86400 |
embed_batch / embed_timeout_s / rerank_timeout_s / embed_wait_s |
16 / 30 / 30 / 120 |
max_sessions |
64 |
文档抽取（10-19 晚新增）
| 键 | 值 | 说明 |
|---|---|---|
documents.enabled |
true（设 false 即回滚整条链路） | |
documents.allow_urls |
false | 只接受上传，不代抓 URL |
max_file_mb / min_text_chars |
20 / 200 | |
max_tokens / reserve_tokens |
120000 / 4096 | 抽取文本的 token 预算与留给对话的余量 |
truncate_head_ratio |
0.7 | 超预算时保留 70% 头部 + 30% 尾部 |
pdf_render_scanned / max_pages / page_tokens / pdf_dpi |
true / 8 / 1024 / 150 | 扫描版 PDF 走页面图 |
max_image_side |
2048 | |
max_xlsx_rows / max_xlsx_cols |
500 / 30 |
留档
| 键 | 值 |
|---|---|
infer_store.enabled |
true |
dir / db |
~/logs/infer-segs / ~/logs/infer.db |
minio_prefix |
infer |
seg_max_mb / seg_max_s / queue_max / capture_max_mb |
8 / 300 / 5000 / 16 |
local_cache_gb / local_cache_days / hot_rows |
4.0 / 7 / 50 |
另有一个
oauth段（含凭据，值不进书）。
B.5 supervisor 程序表（~/deploy/supervisord.conf）
| program | command | autostart | 关键参数 |
|---|---|---|---|
strata |
Strata/run-iq3_xxs.sh |
true | 单实例/split 布局；dual 下被停 |
strata-a |
Strata/run-iq3_xxs-a.sh |
false | dual 才启；layout-restore 负责恢复 |
strata-b |
Strata/run-iq3_xxs-b.sh |
false | 同上 |
rag-proxy |
Strata/.venv/bin/python rag-proxy/rag_proxy.py --config rag-proxy/config.json |
true | startsecs=5、stopwaitsecs=15 |
layout-restore |
Strata/layout-restore.sh |
true | autorestart=false、startsecs=0（一次性） |
共同：autorestart=true、startsecs=15、startretries=3、stopasgroup/killasgroup=true、
stopsignal=TERM、stopwaitsecs=30、日志 ~/deploy/logs/<name>.{out,err}.log（20 MB × 3）、
environment=HF_ENDPOINT="https://hf-mirror.com"。
B.6 改哪个旋钮要重启谁
| 改这里 | 生效方式 | 代价 |
|---|---|---|
rag-proxy/config.json 全部键、rag_proxy.py |
supervisorctl -c ~/deploy/supervisord.conf restart rag-proxy |
秒级，但清空内存会话/嵌入缓存/组装块 |
serve/server.py、frontend.py、lane 配置的 fit_max_tokens / api_monitor / vision.* |
重启该 lane | 6–13 分钟（模型重载） |
lane 配置的 args（--conversation-cache-mib、--prompt-cache-every、--pool-workers、--batch …） |
重启该 lane | 同上 |
STRATA_PREFILL_YIELD_*、STRATA_ESCAPE_SPECIAL |
需要注入到引擎进程环境（改 run-*.sh 或 active-*.env）→ 重启该 lane |
同上 |
TASKSET |
改 run-*.sh 或 active-*.env → 重启该 lane |
同上，错了会崩回 9 tok/s |
| 引擎 C++ | switch-engine dev build → dev run --lane b --yes |
编译 + 6–13 分钟 |
| 前端静态文件 | cd ~/Strata/serve/webapp && bash tools/deploy.sh |
0（serve 直接读盘） |
全部重启类动作都触发红线 1（先经用户同意）。
B.7 本附录小结
- 两条 lane 的引擎
args完全相同，差异只在二进制、CWD、日志路径、gpu、port——
所以"快道更快"不是引擎参数不同，而是车道分工与钉核（11 章、15 章）。 - 真正没设过的旋钮只有四个：
prompt-cache/prompt-cache-every/prompt-cache-root/
conversation-cache-min-free-mib（外加把conversation-cache-mib从 8192 往上抬）。
它们就是 19 章 P1 的全部内容 —— 配置级改动，但要停服窗口。 fit_max_tokens在 ssebed 的strata-b.json里缺失：切 B 到 ssebed 会顺手改掉超窗行为，切换时要一起核对。- 网关配置里
rag_enabled=false让一整族检索旋钮处于休眠；重新启用前先确认窗口预算与max_context一致。 - 引擎那 60+ 个
STRATA_*kernel 开关不属于运维面：它们改的是数值实现，必须过 parity 测试。