企业官网建设流程全解析

本文以 TurboQuant+ 研究仓库中的论文文档 longctx-1m-and-triattention.md 为核心，系统讲解 open-source 长上下文检索服务longctx的两种工作模式（独立检索与 TriAttention V3 救援），并结合 TriAttention V3 论文、仓库源码与测试给出可复现的配置与实测数据。读完本文，你将掌握：如何用 longctx 在 AMD MI300X 上跑通百万 token 级 MRCR v2 检索、如何用ChatSession+ longctx 把 V3 驱逐的 KV 单元"救回"提示词以保住 NIAH 召回、以及生产环境的一整套环境变量默认值。

1. 背景与定位：百万 token 推理的两条路径

当单个 GPU 需要承载百万 token 上下文时，业界出现了两条生产路径：

• 闭源方案（如 SubQ）：专有检索栈 + 模型侧缓存，在 MRCR v2 8-needle 1M 上下文上报出 0.659；
• 开源推理引擎（vLLM、llama.cpp、mlx-swift-lm）：提供模型与 KV cache，但"提示词超出 GPU 内存后怎么办"这个问题留给了应用层。

longctx 正是填补这一空白的组件——一个单一用途的 FastAPI 服务，只做两件事：

1. Index（索引）——将文本片段分块并嵌入 faiss 索引，按 session 或按 repo 划定作用域；
2. Retrieve（检索）——针对查询返回 top-K 片段，可选 rerank。

接线方式决定了它的角色：接在任意 OpenAI 兼容引擎前面，它是 code-aware 的 RAG 层；接在带 query-aware 驱逐策略的引擎（即本项目的 TriAttention V3）后面，它成为"救援层"——把驱逐丢掉的内容接住，并在下一次 prefill 前送回去。

论文报告了两组测量：§3 是 longctx 作为独立检索在 AMD MI300X + Qwen2.5-32B-Instruct 上的 MRCR v2 8-needle 成绩；§4 是 longctx 作为 TriAttention V3 救援层在 Apple M5 Max + Qwen3.5-2B-4bit 上的 256K planted-fact NIAH 成绩。两组均可从开源代码与测试 harness 复现。

需要先厘清一个概念边界：本文所说的 "TriAttention V3" 是本项目自己的独立实现——对 Mao et al. 论文《TriAttention: Efficient Long Reasoning with Trigonometric KV Compression》(arXiv:2604.04921, 2026) 三角打分公式的 Swift 移植与最小混合扩展。prefix-protect（前缀保护）+ per-segment quota（分段配额）混合策略、Tier 2 evict-callback、Tier 3 rehydrate 钩子、Apple Silicon 适配均属于本项目。完整设计见 TriAttention V3。

2. 架构全景

2.1 完整调用栈（顶层视图）

原论文给出了完整的端到端调用栈：

┌──────────────────────────────────────────────────┐ │ CLIENTS (OpenCode / Hermes / curl / your app) │ └────────────────────┬─────────────────────────────┘ │ OpenAI HTTP /v1/chat/completions ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ vllm-swift (Swift HTTP server, --enable-longctx) │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ ChatSession │ │ │ │ • Tier-3 auto-rehydrate hook (commit fe1a3b0) │ │ │ │ • Tokenizer auto-bind into TriAttentionRescue │ │ │ │ • Multi-turn cache persistence │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ mlx-swift-lm (Swift) │ │ │ │ ┌─────────────────────┐ ┌─────────────────────────────────┐ │ │ │ │ │ TokenIterator │ OR │ MTPSpeculativeTokenIterator │ │ │ │ │ │ (standard decode) │ │ (Gemma4Assistant drafter loop) │ │ │ │ │ └──────────┬──────────┘ └──────────┬──────────────────────┘ │ │ │ │ │ │ │ │ │ │ ┌──────────▼──────────────────────────▼──────────────────┐ │ │ │ │ │ Model (Gemma4 / Qwen3 / Qwen3.5 / ...) │ │ │ │ │ │ • newCache(parameters) │ │ │ │ │ │ • forward(inputs, cache) │ │ │ │ │ └────┬───────────────────────────────────────────────┬────┘ │ │ │ │ │ │ │ │ │ │ ┌────▼─────────────┐ ┌──────────────▼──────┐ │ │ │ │ │ KVCache (per │ V3 enabled │ TriAttentionV3 │ │ │ │ │ │ layer) │◀─────────────────│ Engine │ │ │ │ │ │ • Standard │ per-token │ • score / evict │ │ │ │ │ │ • Rotating │ scoring │ • prefix-protect │ │ │ │ │ │ • TurboQuant │ │ • per-segment quota │ │ │ │ │ │ • TriAttention │ └──────────┬──────────┘ │ │ │ │ └──────────────────┘ │ │ │ │ │ │ evict_pos[] │ │ │ │ ┌────────────────────▼──────────┐ │ │ │ │ │ TriAttentionRescue (Tier 2) │ │ │ │ │ │ • decode evicted token IDs │ │ │ │ │ │ • POST /evict/write │ │ │ │ │ └────────────────┬──────────────┘ │ │ │ └───────────────────────────────────────────────┼───────────────────┘ │ └──────────────────────────────────────────────────┼──────────────────────┘ │ HTTP ▼ ┌──────────────────────────────────────────┐ │ longctx-svc (FastAPI, port 5054) │ │ • /evict/write ← evicted text spans │ │ • /evict/retrieve → top-K chunks │ │ • /index, /retrieve ← code-aware mode │ │ • per-session faiss + MiniLM embedder │ └──────────────────────────────────────────┘

栈是对称的：同一个ChatSession路径同时驱动标准解码与 MTP 投机解码，两者都可以开启 V3 驱逐，也都通过相同的/evict/write与/evict/retrieve端点暴露救援桥。这意味着 V3 驱逐、语义检索、前缀缓存这些"算法"都已经存在，百万 token 推理真正的问题变成了管线胶水——而 longctx 就是这层胶水。

2.2 两种工作模式

Code-aware 检索（Mode A/B）。每次 chat completion 的提示词都会被解析出绝对文件路径。通过哨兵文件（package.json、.git、pyproject.toml等）检测首个路径的项目根。longctx-svc 索引该作用域（Hot 优先 → Package 按需），针对用户查询检索 top-K 片段，拼接进 system message 后转发请求。模型看到的是一个顶部带## Retrieved code context块的普通 chat completion。

• Mode A：包装任意 OpenAI 兼容引擎（作为前端代理）；
• Mode B：使用引擎标志--enable-longctx把 longctx-svc 作为 sidecar 拉起来。

两者都能与 TheTom/vllm-swift、TheTom/llama-cpp-turboquant、TheTom/vllm-turboquant 及任何讲 OpenAI HTTP 的上游引擎组合使用。

TriAttention 救援。当推理引擎开启了本项目 TriAttention V3（环境变量VLLM_TRIATT_ENABLED=1、LONGCTX_ENDPOINT=http://...），V3 会在 prefill 期间逐 token 触发驱逐。引擎的救援桥把每个被驱逐的 span（经由绑定的 tokenizer 解码回文本）POST 到/evict/write。下一轮用户消息时，ChatSession自动触发rescue.rehydratePrompt(query: <user_msg>)调用/evict/retrieve，把恢复的片段作为 system message 追加到该轮 prefill 之前。

2.3 为什么两种模式共享同一个索引

两种模式本质都是"文本 span 嵌入到向量索引后的 top-K 检索"，区别只在 span 的来源：

• Code-aware 模式：span 来自磁盘上的仓库（按作用域一次性索引，由文件 watcher 刷新）；
• 救援模式：span 来自 KV-cache 驱逐（推理期间流式产生，按 session 隔离）。

同一套管道服务两者。推理路径额外增加一个以session_id为键的 per-session faiss 存储；code-aware 路径使用 scope-keyed 存储。

2.4 引擎兼容性矩阵

仓库源码层面可以印证该栈与 TurboQuant KV 生态的耦合：本项目 kv_cache.py 中的KVCacheCompressor采用非对称 K/V 处理——K 用完整 TurboQuant（保内积，因为注意力分数依赖 Q@K^T），V 用 PolarQuant MSE-only（保重建质量，因为输出依赖 attn_weights @ V）；而 refract/backends/vllm.py 中的_CTK_CTV_TO_VLLM映射表则把 llama.cpp 风格ctk=...,ctv=...字符串翻译为 vLLM 的kv_cache_dtype（如q8_0/turbo4 → turboquant_k8v4），说明这套检索/驱逐栈是建立在 TurboQuant+ 量化轴之上的"token 数量轴"压缩（详见 TriAttention V3 第 1 节对两轴叠加的讨论）。

3. 独立检索模式：MRCR v2 基准

3.1 实验环境

• 1× AMD Instinct MI300X（192 GB HBM3，gfx942），DigitalOcean 开发者云 droplet，ROCm 7.2，Ubuntu 24.04；
• 模型：Qwen2.5-32B-Instruct（经 TheTom/vllm-turboquant 驱动）；
• 基准：MRCR v2 8-needle（在合成 haystack 中随机位置插入 8 根 needle），按 bin 统计 8K → 1M 上下文成绩。

3.2 三种配方

横跨成本/质量前沿的三组配置：

• plain RAG——单查询检索，无 rerank。最便宜、质量最低；
• single-query Selector + bge-rerank + det copy——标准配方，外加一个确定性 copy 步骤，把检索到的 span 重新锚定回原始提示词框架；
• MultiQ Selector + bge-rerank + det copy——把查询扇出成多个语义变体，取 top-K 并集后再 rerank。最贵、质量最高。

3.3 结果

核心结论：

• n=60 单查询 mass-val：0.601——比 SubQ 的 0.659 低 0.058 绝对值；
• n=30 MultiQ directional：0.688——比 SubQ 的 0.659 高 0.029。mass-val 复跑尚未完成；一次 n=80 的优先运行在 droplet 上 OOM 提前终止。

需要谨慎表述的部分：MultiQ 配方以查询延迟换准确率，1M 处的领先是真实的但仍是 provisional，要等 mass-val 数字落地才能定论；1M 单查询才是保守主张。

3.4 延迟

longctx-svc热/retrievep95 为63.2 ms。冷作用域构建（20 文件项目）12.7 s。磁盘缓存重载 8.9 s（大头是 embedder 冷加载）。测试覆盖 173 个测试、全绿——这与仓库测试体系一脉相承（仓库 tests/ 目录下有 14 个测试文件、500+ 测试的覆盖面记录于 README.md）。

4. 救援模式：TriAttention V3 + longctx

本节中 "TriAttention V3" 均指本项目的 V3——Mao et al. 三角打分公式的独立 Swift 移植与最小混合扩展。完整设计与逐架构结果见 TriAttention V3。

4.1 实验环境

• 1× Apple M5 Max，128 GB unified memory，macOS 26.4；
• 模型：mlx-community/Qwen3.5-2B-4bit（qwen3_5 混合 Mamba+Attention 架构，4-bit 量化）；
• 引擎：TheTom/mlx-swift-lm 的feature/triattention-v3分支；
• 测试 harness：Tests/Benchmarks/V3ChatSessionRamp.swift；
• 驱逐配置：V3 默认率（10%），window=128，prefix=32，warmup=256，hybrid=2。

4.2 三臂接线

每个上下文档位（32K / 64K / 128K / 256K）跑三臂对照：

• baseline-tq8v4——单轮提示词内置 planted fact + 问题，turbo8v4 KV codec，无 V3、无 longctx。确立模型原生上下文窗口下的召回基线；
• v3-only——两轮结构，V3 开启，longctx 关闭。检验 V3 单独能否保住召回；
• v3+longctx——两轮结构，V3 开启，LONGCTX_ENDPOINT=http://127.0.0.1:5054。检验完整救援栈。

两轮结构是必要条件：ChatSession的 auto-Tier-3 rehydrate 钩子在该轮 prefill之前用该轮用户消息文本作为查询触发。单轮提示词在驱逐已经发生之前没有任何东西可供 rehydrate 钩子查询。因此要把长 blob 和问题拆成两轮：第 1 轮驱逐填充 longctx 索引，第 2 轮问题才触发救援检索。

4.3 逐轮流程

USER TURN N (long blob: filler + planted fact) │ ▼ ChatSession.respond(prompt) │ ▼ Build messages list, run prefill │ ▼ Model forward, layer-by-layer: ┌─────────────────────────────────────────────────────────┐ │ for each layer: │ │ attention(Q, K, V) → cache.update(K, V) │ │ V3.accumulateLayerScore(K, layerIdx) │ │ when cumulative cells > budget + divideLength: │ │ evict_pos = V3.finalizeEvictRound() │ │ for c in cache: │ │ c.removePositions(evict_pos) │ │ ┌─────────────────────────────────────────────┐ │ │ │ TriAttentionRescue.shared.onEvict(spans) │ │ │ │ ├─ tokenizer.decode(evicted_ids) │ │ │ │ └─ POST /evict/write?session_id=... │ ────┼──▶ longctx-svc │ └─────────────────────────────────────────────┘ │ ingests, embeds, └─────────────────────────────────────────────────────────┘ indexes in faiss │ ▼ Generate "OK" ack (turn N output) USER TURN N+1 (the question — "What's the access code?") │ ▼ ChatSession.respond(question) │ ▼ ┌─────────────────────────────────────────────────────────┐ │ TIER-3 AUTO-REHYDRATE (only fires through ChatSession) │ │ if any cache is TriAttentionKVCache: │ │ recovered = rescue.rehydratePrompt(query=question) │ ────▶ POST /evict/retrieve │ if recovered: │ ◀── top-K chunks │ messages.insert(.system(recovered), │ │ before user_msg) │ └─────────────────────────────────────────────────────────┘ │ ▼ Prefill turn N+1 (now sees recovered chunks containing planted fact) │ ▼ Generate answer ─────▶ "481729" ✓HIT

4.4 结果

ctx arm t1 t2 v3% rounds recall total 32K baseline-tq8v4 5.6s 0.0s 0.00% 0 ✓HIT 5.6s 32K v3-only 6.8s 0.2s 3.72% 12 ✗miss 6.9s 32K v3+longctx 7.7s 0.6s 3.72% 12 ✓HIT 8.3s 64K baseline-tq8v4 16.7s 0.0s 0.00% 0 ✓HIT 16.7s 64K v3-only 19.5s 0.2s 2.17% 18 ✗miss 19.7s 64K v3+longctx 20.9s 0.9s 2.17% 18 ✓HIT 21.8s 128K baseline-tq8v4 76.3s 0.0s 0.00% 0 ✓HIT 76.3s 128K v3-only 66.9s 0.8s 1.42% 24 ✗miss 67.6s 128K v3+longctx 69.5s 1.3s 1.42% 24 ✓HIT 70.9s 256K baseline-tq8v4 186.7s 0.0s 0.00% 0 ✓HIT 186.7s 256K v3-only 220.9s 1.0s 1.32% 30 ✗miss 221.9s 256K v3+longctx 226.9s 2.4s 1.32% 30 ✓HIT 229.3s

4.5 发现

• V3+longctx 在 32K → 256K 每一档都通过召回；
• V3 单独在每一档都失败：默认策略下无论上下文多大，V3 都会驱逐 planted fact，且没有任何机制恢复它；
• baseline turbo8v4 每一档都通过召回：模型原生上下文窗口无需 V3 或 longctx 就能干净处理 256K——V3 只在提示词长度超出 GPU 内存预算时才变得必要；
• 256K 处栈开销 vs baseline 约 +22%（229s vs 187s）：成本是一次变两次的 prefill 轮次 + rehydrate 查询延迟，收益是模型原生窗口之上的无界有效上下文；
• V3 驱逐率随上下文增大而下降：3.72% @ 32K → 1.32% @ 256K。推测原因是 warmup/prefix/window 保护区域在总可驱逐单元中的占比随上下文增长而缩小，策略在长上下文下趋于保守。

这里有一个容易误读的细节值得点破（姊妹论文 TriAttention V3 §10.4 也专门解释）：v3-only 列在某些档位反而更快（128K 时 66.9s < baseline 的 76.3s），因为 V3 驱逐单元缩小了 decode 期间的有效 KV。但决定成败的是召回列——✗miss 的更快一臂是"坏的更快"，不是改进。

4.6 写路径的独立确认

一个独立的 256K 单细胞测试（默认 10% 驱逐率）确认救援写回调稳定触发：

prompt_tok=247753, budget=230400 prefill=224.55s, decode=6.22s, tps=10.1 v3_rounds=30, v3%=1.32% longctx_session_total=19427 ← chunks ingested by longctx-svc recall=✗miss ← bare container.generate() doesn't rehydrate

第 1 轮 prefill 期间 longctx-svc 摄入了19,427 个被驱逐文本块。该测试 recall=✗miss 的原因是该 harness 调用了裸container.generate()而非ChatSession.respond()——auto-Tier-3 rehydrate 钩子只接在ChatSession路径上（对应 mlx-swift-lm 的 commitfe1a3b0）。裸驱动必须在每次 prefill 前手动调用TriAttentionRescue.shared.rehydratePrompt(query:)。

5. 没有 longctx 时 V3 的失败模式

第 4 节最干净的结论是：本项目 TriAttention V3 单独使用，对长上下文检索负载是不安全的。

V3 的驱逐策略在"查询感知"的意义上是指：它按细胞对近期查询的注意力显著性打分。但 planted-fact NIAH 把问题放在事实之后——等到问题的 query 开始给细胞打分时，V3 早已驱逐了包含事实的细胞。驱逐是单向的：从 KV 里消失的细胞就是消失了。

longctx 让驱逐可逆。被驱逐的 span 在写时刻被捕获、嵌入、索引。当下一轮查询到来时，语义检索找到相关 span 并把它放回提示词前面——模型在提示词里拿到的，正是 V3 从缓存里拿掉的那个事实。

这个依赖关系已写进 mlx-swift-lm 的 README（"Critical: don't enable V3 without longctx"），并附上第 4 节的实证回执表。姊妹论文 TriAttention V3 §10.7 进一步说明：这个修复不改变 V3 的打分算法——在已测的模型规模（2B-4bit Qwen3.5）与上下文（32K-256K）下，救援层补偿了 V3 错误驱逐的细胞，无需任何算法改动即可让混合架构上的 V3 可发布；§7.1 提出的三条打分假设（partial-RoPE 盲区、phase-only 打分、M-RoPE theta 缩放）依然成立，但属于"更优 V3"的科研问题，而非"能发布 V3"的工程问题。

6. 生产默认配置

对 M 系列 Apple Silicon 上长上下文的 Gemma 4 / Qwen3 / Llama 类模型：

# 1. longctx service longctx-svc serve --host 127.0.0.1 --port 5054 # 2. inference engine env export VLLM_TRIATT_ENABLED=1 export VLLM_TRIATT_BUDGET=$((CTX_TARGET * 9 / 10)) # 10% eviction headroom export VLLM_TRIATT_WINDOW=128 export VLLM_TRIATT_PREFIX=32 export VLLM_TRIATT_WARMUP=256 export VLLM_TRIATT_HYBRID=2 export LONGCTX_ENDPOINT=http://127.0.0.1:5054

驱动方式二选一：走ChatSession（mlx-swift-lm），或 vllm-swift 的--enable-longctx标志。自定义驱动必须手动接 rehydrate 钩子。

AMD MI300X + TheTom/vllm-turboquant 时，longctx-svc 跑在同一 droplet 上，引擎的--enable-longctx标志负责 sidecar 拉起。

各参数含义与取值范围见附录 C。需要说明VLLM_TRIATT_BUDGET的语义：它表示驱逐触发前要保留的 KV 单元数，默认配置要求显式给出（例如ctx × 0.9即 10% 驱逐余量）；VLLM_TRIATT_HYBRID=2选择 V3 选择策略（0=V1 论文原版全局排序、1=V2 仅分段配额、2=V3 前缀保护+分段配额），这与 llama.cpp 侧--triatt-hybrid 2的语义一致（见 TriAttention V3 §6.4）。

7. 局限性与未决事项

• V3 + TQ+ 叠加仍被门控。TriAttentionKVCache继承自KVCacheSimple（仅 FP16）。要把 V3 与 TurboQuant codecs（turbo8v4、turbo4v2）叠加，需要TriAttentionTurboKVCache变体——已跟踪、尚未发布；
• V3 钩子是按模型族接线的。目前接在 Qwen3 / Qwen3.5 / Qwen3-MoE / Llama / Mistral3 / Phi / Phi3 / Gemma3 / GLM4 上，其他模型族回退到非 V3 缓存；
• MRCR v2 1M MultiQ 的 n=60 mass-val 待跑。当前是高于 SubQ 的 directional n=30 结果 + 低于 SubQ 的保守单查询 mass-val；
• 裸container.generate()跳过救援。auto-Tier-3 rehydrate 仅限ChatSession，自定义驱动需显式调用rehydratePrompt(query:)；
• 两轮结构的延迟代价。单轮长上下文 + V3+longctx 需要要么（a）模型的问题来自 haystack 之后的独立 API 轮，要么（b）用问题文本显式做 pre-prefill rehydrate。两轮模式对聊天天然；文档/单发推理模式需要集成工作。

姊妹论文 TriAttention V3 还记录了两条与本主题直接相关的边界事实：在 256K 以上尚无 V3+longctx 数据（1M 的 MRCR 结果是 AMD 上无 V3 的独立检索）；尚未在更大的 Qwen3.5-27B / 35B-A3B 上验证（Apple Silicon 测试因显存余量选择了 2B），预期同模式成立但等待硬件验证。

8. 结论

longctx 同时交付两样东西：一个能通过 CLI 标志包装任意 OpenAI 兼容引擎的 code-aware 检索伴生服务；一个面向 query-aware KV 驱逐策略的救援层，让引擎在不损失召回的前提下运行实际上无界的上下文。

MRCR v2 数字把 longctx 放在 1M 上下文下 SubQ 的可及范围内（MultiQ 配方 0.688 directional vs 0.659），等待 mass-val 落地；TriAttention 救援数字则毫不含糊：V3 单独每一档都 miss，V3+longctx 每一档都 hit——"这对组合"才是功能单元，不是其中任何单件。

开源推理引擎现在有了单 GPU 百万 token 上下文的路径，无需闭源专有栈。算法存在（V3 驱逐、语义检索、前缀缓存），胶水也存在（longctx）。剩下的工作是集成覆盖与栈级优化（V3+TQ+、drafter 配对的 MTP 等），而非算法发明。

9. 复现

# longctx-svc git clone https://github.com/TheTom/longctx cd longctx && pip install -e . longctx-svc serve --host 127.0.0.1 --port 5054 # mlx-swift-lm V3+longctx ramp (Apple Silicon) git clone -b feature/triattention-v3 https://github.com/TheTom/mlx-swift-lm cd mlx-swift-lm RUN_V3_CHAT_RAMP=1 swift test --filter "V3ChatSessionRamp" # vllm-turboquant on AMD MI300X (1M MRCR) # see longctx/docs/results.md for the full recipe

带原始日志与逐细胞回执的发现文档随测试源码一并提供。仓库内可交叉验证的相关材料包括：TriAttention V3（V1/V2/V3 策略演进与全量数值附录）、asymmetric-kv-compression.md（K/V 非对称压缩原理）、kv_cache.py（K/V 双路量化实现）、refract/backends/vllm.py（KV preset 翻译表）。

附录 A：mlx-swift-lm 侧模块图

mlx-swift-lm/ ├── Libraries/ │ ├── MLXLMCommon/ │ │ ├── ChatSession.swift ← Tier-3 auto-rehydrate hook (commit fe1a3b0) │ │ ├── Evaluate.swift ← TokenIterator + SpeculativeTokenIterator │ │ ├── KVCache.swift ← Standard / Rotating / TurboQuant base │ │ └── TriAttention/ │ │ ├── TriAttentionV3.swift ← engine, scoring, eviction policy │ │ ├── TriAttentionKVCache.swift← V3 cache (extends KVCacheSimple, FP16) │ │ └── TriAttentionRescue.swift ← Tier 2 evict-write + Tier 3 rehydrate │ │ │ ├── MLXLLM/ │ │ ├── LLMModelFactory.swift ← model_type registry (incl. gemma4_assistant) │ │ └── Models/ │ │ ├── Gemma4.swift ← parent (V3 hook in newCache) │ │ ├── Gemma4Assistant.swift ← MTP drafter (4-layer Q-only) │ │ ├── MTPSpec.swift ← MTP iterator (parent verify + drafter loop) │ │ ├── Qwen3.swift / Qwen35.swift / Qwen3MoE.swift │ │ ├── Llama.swift / Mistral3.swift / Phi.swift / Phi3.swift │ │ └── Gemma3.swift / GLM4.swift / ... │ │ │ └── MLXVLM/ ← VLM models (separate factory) │ └── Tests/Benchmarks/ ├── V3ChatSessionRamp.swift ← 12-cell V3+longctx ramp (§4 receipts) ├── V3ChatSessionNIAH.swift ← 256K NIAH end-to-end via ChatSession ├── V3CtxRamp.swift ← bare container.generate (no rehydrate) ├── V3DefaultTest.swift ← single 256K w/ default 10% rate ├── TurboCtxRamp.swift ← turbo8v4 ramp 32K → 256K └── MTPSpecDecode.swift ← Gemma 4 31B MTP bench (separate from V3)

附录 B：longctx-svc 端点面

POST /evict/write?session_id=<id> body: {"chunks": [{"text": "...", "tokens": [...], "round": N, "layer": L}]} → MiniLM embed → faiss store keyed by session_id POST /evict/retrieve?session_id=<id> body: {"query": "<user message text>", "top_k": 8} → faiss search → top-K chunks formatted as system message text GET /evict/dump?session_id=<id> → {"session_total": int, "chunk_summary": [...]} (debug) POST /index?scope=<path> (code-aware mode) → walk repo, chunk, embed, faiss store keyed by scope POST /retrieve?scope=<path>&query=<text>&top_k=K (code-aware mode) → top-K spans formatted as system message text GET /healthz → {"status": "ok", "version": "0.3.0a3"} GET /longctx/status → human-readable session/scope state

附录 C：V3 环境变量

姊妹论文 TriAttention V3 的 vLLM 移植篇（§9.9.4）提供了本表的扩展版本，补充了VLLM_TRIATT_SEGMENTS（分段配额桶数，默认 8）、VLLM_TRIATT_ADAPTIVE（EMA 更新校准中心，默认 0）等旋钮，并给出了 Python 侧install_triattention(model_path, cfg)与纯环境变量两种等效启用方式——两篇文档的参数语义完全对齐，可互为参照。