项目定位与目标

cactus-hybrid 是 Cactus 团队在其端侧推理引擎基础上扩展出的混合执行组件，目标是在同一套调用接口下，把本地（on-device）推理与远端（cloud）推理组合起来，依据运行时条件动态选择最合适的执行路径 资料来源：README.md:1-30。仓库以 Python 包的形式发布，遵循许可证条款进行分发 资料来源：LICENSE:1-15。项目元数据（如包名、版本、依赖）通过标准的 pyproject.toml 管理，便于集成到既有的 Python 工程中 资料来源：pyproject.toml:1-40。

混合路由核心概念

“混合路由”（Hybrid Routing）是该项目的核心抽象：当一段推理请求进入时，路由器（router）会根据一系列策略信号——例如设备算力、当前电量、网络可用性、模型尺寸、提示词长度或用户自定义规则——决定把请求委派给本地后端还是云端后端，并能够在两者之间做结果合并或回退 资料来源：cactus_hybrid/router.py:1-60。这一设计避免了把“全部本地”或“全部云端”作为单一默认选项，让应用能够在隐私、时延、成本之间灵活权衡 资料来源：README.md:30-80。

flowchart LR
    A[用户请求] --> B[HybridRouter]
    B --> C{路由策略评估}
    C -- 本地优先 --> D[LocalBackend]
    C -- 云端优先 --> E[CloudBackend]
    D --> F[结果合并/回退]
    E --> F
    F --> G[返回调用方]

系统架构与组件

整个项目由入口模块、路由器、配置对象以及若干后端实现组成。cactus_hybrid/__init__.py 暴露了对外的顶层 API，使调用方无需关心内部模块路径即可完成推理调用 资料来源：cactus_hybrid/__init__.py:1-20。

• 配置层：config.py 定义了路由策略、超时阈值、降级条件等可调参数，使策略与代码逻辑解耦 资料来源：cactus_hybrid/config.py:1-50。
• 路由器层：router.py 实现了策略匹配与请求分发逻辑，是混合行为的中枢 资料来源：cactus_hybrid/router.py:60-140。
• 本地后端：backends/local.py 封装了 Cactus 原生端侧推理能力，优先保证数据不出设备 资料来源：cactus_hybrid/backends/local.py:1-45。
• 云端后端：backends/cloud.py 负责与远端推理服务通信，用于处理本地无法覆盖的大模型或高复杂度任务 资料来源：cactus_hybrid/backends/cloud.py:1-45。

配置与使用流程

典型使用流程包含三个步骤：首先在 Config 中声明希望的路由偏好（例如 “本地优先、超过某 token 数走云端”），然后构造 HybridRouter 实例并注入对应的后端对象，最后通过统一入口发起推理；路由器会自动应用策略并在必要时做后端切换或结果融合 资料来源：cactus_hybrid/config.py:50-90 资料来源：cactus_hybrid/router.py:140-200。通过将策略集中在配置层，cactus-hybrid 让开发者可以在不改业务逻辑的前提下，针对不同终端形态与网络环境调优路由行为 资料来源：README.md:80-120。

套件定位与目标

该补丁套件位于仓库 patches/llama.cpp/ 目录,是一套针对上游 llama.cpp 项目的本地化补丁系统,核心目标是引入并稳定支持 Gemma 4 E2B It 的混合 (hybrid) 模型架构。套件覆盖了从权重存储、模型转换、推理运行时,到本地 HTTP 服务的完整链路,并配套测试入口形成闭环。

由于 Gemma 4 E2B It 是一种包含 handoff (注意力→局部 FFN→全局 FFN) 的混合架构,上游 llama.cpp 尚未原生支持,因此本套件通过补丁的方式将其纳入 llama.cpp 的 GGUF 元数据、转换脚本与运行时栈中。资料来源：patches/llama.cpp/README.md:1-40

目录结构与文件职责

补丁套件采用典型的“版本锁定 + 顺序补丁 + 构建脚本”三段式布局:

资料来源：patches/llama.cpp/README.md:1-40、patches/llama.cpp/PIN:1-3、patches/llama.cpp/apply.sh:1-40、patches/llama.cpp/install.sh:1-40

补丁链与构建工作流

套件工作流遵循 “PIN → apply → install” 的顺序,确保对上游的修改可追溯且可重复:

flowchart LR
    A[上游 llama.cpp<br/>由 PIN 锁定] --> B[apply.sh<br/>按编号顺序应用 patches/]
    B --> C[0001 gguf-py 架构扩展<br/>含 handoff 元数据]
    C --> D[0002 convert 转换脚本<br/>Gemma4E2BItHybridForCausalLM]
    D --> E[install.sh<br/>cmake 编译与安装]
    E --> F[hybrid 版 llama.cpp<br/>runtime + server + tests]

apply.sh 通过 git apply 或 patch 将 patches/ 下的文件按 0001-、0002- 前缀顺序打补丁。install.sh 则负责执行 cmake 配置、make/ninja 编译,并将可执行文件安装到本地前缀,供后续 cactus 运行时调用。

GGUF 与转换支持 (运行时/服务/测试基础)

两个补丁分别覆盖存储格式与权重转换两个层面:

• 补丁 0001:gguf-py 侧注册新架构 gemma4_e2b_it_hybrid,并在 GGUF 元数据中编码 handoff (从全局注意力过渡到密集 FFN 的特殊 token/层配置),确保 GGUF 文件可被运行时正确解析。资料来源：patches/llama.cpp/patches/0001-gguf-py-add-gemma-4-e2b-it-hybrid-arch-with-handoff-.patch:1-80

• 补丁 0002:在 convert_hf_to_gguf.py 中新增对 Gemma4E2BItHybridForCausalLM 的识别与转换逻辑,使 Hugging Face 权重的张量能够正确映射到 GGUF 的张量名称与形状,特别是 hybrid 部分的专家/局部权重。资料来源：patches/llama.cpp/patches/0002-conversion-support-Gemma4E2BItHybridForCausalLM-gemm.patch:1-80

补丁生效后,即可在本地 llama.cpp 中复用其内置的 llama-cli 运行时、llama-server HTTP 服务以及单元测试入口,对 Gemma 4 E2B It hybrid 模型进行端到端的 GGUF 加载、推理与服务暴露,从而为上层 cactus-hybrid 提供统一的本地 LLM 推理基座。

概述与目标

cactus-hybrid 项目围绕"混合推理"展开：在一个统一的 LLM 服务端内串联多种规模的模型（例如完整大模型 + 轻量模型），并在 token 生成过程中按需切换执行路径。"置信度探针与 Handoff API" 是该项目的核心机制之一，负责在推理过程中检测当前路径的生成质量，并在满足条件时将控制权（Handoff）从重模型交还给轻量级解码阶段。

其核心目的包括：

• 可观察性：暴露每一次探针的原始分数、归一化后的置信度以及阶段切换原因；
• 可控性：提供运行时（runtime）与暂存（staging）两套 API，使上层调用方既能立即读出结果，也能缓存以待后续比对；
• 可移植性：通过 server 端的 patch（0005）将探针结果标准化，并以 JSON 形式输出到日志或响应字段；
• 可验证性：通过黄金用例 patch（0006）锁定 Gemma 4 E2B-IT 在 Hybrid 模式下的预期行为，避免回归。

资料来源：README.md:1-80

运行时与暂存 API

0004-llama-add-handoff-probe-runtime-and-staging-API.patch 是整个特性的底层入口，向 llama.cpp 的 C/C++ 上下文结构中新增了一组用于"探针—决策—暂存"的接口。其主要数据结构与函数可分为三层：

1. 运行时层（Runtime）：在每一轮 token 评估之后立即触发，不阻塞当前 decode 循环，向调用方回传当前 logits 的统计信息（top-k 概率、熵、归一化得分）；
2. 决策层（Decision）：依据运行时层产出的指标计算 confidence ∈ [0, 1]，并对照预设阈值判断是否触发 Handoff；
3. 暂存层（Staging）：将未立即消费的探针结果写入环形缓冲区，供上层在后续 N 个 token 内按需比对或回滚。

这种"探针 + 暂存"的组合可以避免在低置信度时直接打断生成路径，而是把决策信息累积到 staging 区域，让上层策略（例如调度器、UI）拥有完整上下文。

资料来源：patches/llama.cpp/patches/0004-llama-add-handoff-probe-runtime-and-staging-API.patch:1-120

服务端置信度报告（Gemma 4 E 系列）

0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch 负责把底层探针结果桥接到 HTTP/Server 端。当模型是 Gemma 4 E 系列（例如 gemma-4-e2b-it）且运行在 Hybrid 模式下时，Server 会在响应体与日志中追加 handoff_probe 字段，结构大致如下：

• probe_score：归一化后的置信度（0–1）；
• harness：触发探针的执行阶段标识（如 draft、verify、fallback）；
• decision：accept / handoff / defer 三态；
• staging_ref：指向暂存层中保留该决策的引用 id，便于客户端做长程一致性校验。

服务端通过统一的字段名对外暴露，使得不同模型（例如未来加入的更大规模 E 系列变体）可以共享同一套前端埋点和 A/B 框架。

资料来源：patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch:1-90

测试与黄金用例

0006-tests-add-gemma-4-e2b-it-hybrid-handoff-probe-golden.patch 为该特性引入了端到端的"黄金用例"（golden test）。它在 tests/ 目录下登记了一组固定的输入 prompt 与 Hybrid 配置，运行后将输出与 *.golden 文件逐字段对比：

prompt: "请简要说明 Hybrid 推理的优势。"
expected.handoff_probe.decision = "handoff"
expected.handoff_probe.probe_score ∈ [0.62, 0.81]
expected.staging_ref 必须非空

这一用例既覆盖了运行时层的阈值边界，又覆盖了暂存层的引用完整性，是验证 0004 与 0005 协同行为的关键保障。任何对阈值、字段名或 staging 行为的修改都必须同步更新对应的 golden 文件，否则 CI 立即失败。

资料来源：patches/llama.cpp/patches/0006-tests-add-gemma-4-e2b-it-hybrid-handoff-probe-golden.patch:1-140

工作流总览

flowchart LR
    A[llama_decode] --> B[Probe Runtime]
    B --> C{confidence ≥ threshold?}
    C -- 是 --> D[写入 Staging<br/>decision=accept]
    C -- 否 --> E[写入 Staging<br/>decision=handoff]
    D --> F[继续当前路径]
    E --> G[Server 报告 handoff_probe]
    G --> H[客户端/调度器触发 Handoff]

整条链路强调"先观察、后决策、再切换"的解耦思想：探针只负责客观测量，决策由 Server 层统一输出，Handoff 动作由上层策略最终执行，从而让 Hybrid 推理在可控、可解释的前提下运行。

资料来源：README.md:60-120, patches/llama.cpp/patches/0004-llama-add-handoff-probe-runtime-and-staging-API.patch:60-200, patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch:30-110, patches/llama.cpp/patches/0006-tests-add-gemma-4-e2b-it-hybrid-handoff-probe-golden.patch:20-160

本指南聚焦 cactus-hybrid 在生产或开发环境的部署、跨推理后端（Cactus 原生后端与 llama.cpp 衍生后端）切换、以及日常运维关键操作。仓库通过 patches/、scripts/、tools/、configs/、docker/ 五个目录协同提供一站式安装—补丁—构建—运行链路；运维则围绕启动脚本、日志路径、握手探针（handoff probe）三方面展开 资料来源：README.md:1-80。

部署流程与脚本编排

仓库建议以 patches/llama.cpp/install.sh 与 patches/llama.cpp/apply.sh 作为安装入口：前者负责克隆并检出与本仓兼容的 llama.cpp 子版本，后者按顺序叠加 patches/llama.cpp/patches/0001-… 至 0005-… 系列补丁，确保 llama-server 暴露本仓自定义的“握手探针置信度”字段；随后通过 scripts/prepare.sh 准备模型与 tokenizer 缓存目录，scripts/run-server.sh 启动 HTTP 推理服务 资料来源：patches/llama.cpp/install.sh:1-40、资料来源：patches/llama.cpp/apply.sh:1-40、资料来源：scripts/prepare.sh:1-40、资料来源：scripts/run-server.sh:1-40。

跨平台发布可借助 scripts/build-cross.sh，通常会针对 linux/amd64、linux/arm64 矩阵分别执行 CMake 与 cactus 静态库构建，并在产物阶段携带 llama-server 主可执行文件；容器化路径则可直接基于 docker/Dockerfile 构建，其中固化了相同的补丁顺序与构建参数 资料来源：scripts/build-cross.sh:1-40、资料来源：docker/Dockerfile:1-40。

跨后端切换与配置

cactus-hybrid 同时支持“原生 Cactus 后端”与“llama.cpp 派生后端”，二者通过 configs/server.yaml 的 backend: 字段切换：

切换后端时，tools/init.sh 会调用对应后端的健康检查端点（/health 与 /v1/models），验证模型加载与握手探针字段是否存在；若字段缺失，则说明 patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch 未应用或顺序错误，应回到 patches/llama.cpp/apply.sh 重新应用 资料来源：configs/server.yaml:1-40、资料来源：tools/init.sh:1-40、资料来源：patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch:1-40。

部署架构概览

flowchart LR
  A[客户端请求] --> B[Cactus 路由层]
  B -- backend=cactus --> C[Cactus 原生引擎]
  B -- backend=llama_cpp --> D[llama-server<br/>含 handoff probe]
  C --> E[模型权重 GGUF]
  D --> E
  D -- X-Cactus-Probe-Confidence --> B

docs/deployment.md 强调：Cactus 路由层读取 X-Cactus-Probe-Confidence 后决定是否将请求“交接（handoff）”给原生后端以获得更高吞吐，因此部署时务必保证 llama-server 补丁被正确打上，否则路由降级为单一后端 资料来源：docs/deployment.md:1-40。

运维关键操作

1. 补丁一致性检查：定期在 CI 中执行 bash patches/llama.cpp/apply.sh --check，确保 0005- 补丁随升级持续生效。
2. 健康探活：scripts/run-server.sh 默认暴露 /healthz（Cactus 后端）与 llama-server 的 /health；二者任一返回 200 才视为集群健康。
3. 日志与指标：容器化部署时建议挂载 /var/log/cactus 目录，并通过 llama-server 的 --log-format json 抓取 probe_confidence 指标用于回溯交接决策。
4. 滚动升级：先替换 docker/Dockerfile 产物，再以蓝绿方式切换 configs/server.yaml 中 server.report_handoff_probe 字段，最后执行 scripts/prepare.sh 预热新权重。

跨后端灰度策略可参考 docs/backends.md，其中描述了基于 X-Cactus-Probe-Confidence 阈值（例如 >= 0.85）在两个后端间分配流量的方法 资料来源：docs/backends.md:1-40、资料来源：README.md:60-80。

Pitfall Log / 踩坑日志

项目：cactus-compute/cactus-hybrid

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 cactus-hybrid 与安装入口 cactus-compute 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：pip install cactus-compute
• 证据：identity.distribution | https://news.ycombinator.com/item?id=49010782 | repo=cactus-hybrid; install=cactus-compute

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://news.ycombinator.com/item?id=49010782 | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49010782 | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=49010782 | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=49010782 | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49010782 | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49010782 | release_recency=unknown