mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-26 20:33:15 +00:00
7799ca4559
上一提交的基准结论是错的："C 比 Go 慢" 不成立 —— 那是我把自己的
malloc/拷贝开销误当成了 cgo 的固有成本。本提交先拆解成本、再逐项消灭。
## 成本拆解（同机、百万次 benchtime）
| 场景 | ns/op |
|---|---:|
| cgo 边界（零拷贝传指针 + 空函数体）| 31.9 ← cgo 真实固有成本 |
| + 一次 C.CString + C 侧 strlen | 105-111（多出 ~75ns）|
| 初版 ModelContextWindow（另加 lower_dup malloc + 16×strstr）| 175 |
即 82% 开销是自找的。而初版还违反了自己写在设计文档 §四 的原则第 1 条
「C 接口只吃 const char* + 长度」——它没传长度，让 C 侧 strlen 再扫一遍。
## 逐项修复
1. C.CString（malloc+整串拷贝）→ unsafe.StringData 传指针+长度，零拷贝
2. C 侧 strlen 再扫一遍 → 长度由调用方传入，不扫
3. truncate 的 malloc 输出缓冲 + GoStringN 拷回 → C 只返回**字节数**
（结果必然是输入前缀），Go 侧 s[:n] 完成切片，全程零分配
4. lower_dup 每次 malloc 模型名 → 栈缓冲折叠，超长走零分配回退
5. 逐字节 utf8_next 函数调用 → 字级（8 字节）ASCII 检测
6. truncate 扫完整串才判断 → 数满 keep 个 rune 立即返回（提前短路）
7. 纯 Go 侧 len([]rune(s))/[]rune(s)（1KB 分配 4KB）→
utf8.RuneCountInString / DecodeRuneInString 游走，零分配
## 结果
| 基准 | 初版 C | 优化后 C | 纯 Go | 提升 |
|---|---:|---:|---:|---:|
| ModelContextWindow | 175 | 76.5 | 46.8 | 2.3× |
| EstimateTokens / 1KB ASCII | 2318 | 80.8 | 326 | 28.7× |
| TruncateByTokens / 1KB ASCII | 2594 | 71.7 | 411 | 36× |
| TruncateByTokens / 1KB 中文 | 3923 | 70.1 | 3097 | 56× |
## 完全 C 化（jianf 裁定）
撤掉我一度加的「短串 <32B 走回 Go」按长度分派：那会同时存在两份语义
可能分叉的实现。C 是唯一实现。
代价如实记录：EstimateTokens("qq") 这类极短串上 C 约 47ns（几乎全是
31ns 边界成本）vs 纯 Go 约 3ns，慢约一个数量级；绝对值纳秒级
（0.000047ms），单次请求尺度可忽略。若某循环对极短串高频调用，
正确应对是**把该循环 C 化（批量传一次）**，而不是按长度分派回 Go。
## 顺带补的正确性缺口（初版是真错的）
初版 C 的 UTF-8 解码只按首字节推断长度、**不校验后续字节**，
因此对畸形序列会与 Go 分叉：例 "\xE4\x41\x41"，Go 判 3 rune，
初版判 1 rune ⇒ rune 计数偏差 ⇒ token 预算与截断点偏移。
这类偏差**只影响计数、不会崩**，不测发现不了。
现在 C 侧做与 utf8.DecodeRuneInString 等价的完整校验（含过长编码、
代理对、超 U+10FFFF、截断序列），语义边界逐条注释。
代价：中文密集输入比初版慢（1467 vs 840）—— 这是刻意的正确性代价，
且仍比纯 Go 快 2×。
新增测试：
- TestGolden_InvalidUTF8：3000 组**任意字节**（含畸形序列）对拍，
覆盖初版会分叉的输入类别
- TestGolden_TruncateAlwaysPrefix：截断结果必为原串前缀且不超长
- C 契约测试从 21 项扩到 40 项（含非 NUL 结尾、超长名、畸形 UTF-8）
## 包现在要求 cgo 才能编译
删除 codec_nocgo.go：CGO_ENABLED=0 下整包构建失败（错误直指缺失符号）。
不保留回退的理由：只验证过一条路，就不该存在第二条。
实测这不影响任何构建 —— go list -deps 证明只有 cmd/homed 依赖本包，
而 waiter/initconfig/memgc/mock-server 均不依赖（逐个验过），
且 homed 本就强制 cgo（sqlite3 + gojieba）。仓库无 CI。
Makefile 把「不许有第二条路」变成可执行断言：check-codec-cgo-only
（断言 cgo 下全绿 **且** CGO_ENABLED=0 下必须失败）。
## 验证
- C 契约测试 40/40（gcc -Wall -Wextra 零警告）
- 黄金对照 6 个测试全绿（含 2000 组随机 + 3000 组畸形字节对拍）
- 变异测试：改 C 侧返回值后 go test 立即 FAIL（确认真的走 C）
- make check-codec-cgo-only 两项断言通过
- go vet ./... 干净；全量 go test -count=1 ./... → 38 ok / 0 FAIL
## 已知既有 flaky（与本改动无关，单独记录）
internal/plugins 在全量并发下偶发一次 SIGSEGV，栈在
internal/plugin/proc/{unified.go:234,arena.go:197}（arena 的 getU32）。
该两文件最后修改于 09-10，本提交 0 处触及；随后连跑 5 次单包 +
2 次全量均通过。初步判断是 arena/shared-region 的既有竞态，需单独排查。
87 lines
3.8 KiB
C
87 lines
3.8 KiB
C
#ifndef HA_CODEC_H
|
||
#define HA_CODEC_H
|
||
|
||
/*
|
||
* ha_codec — HomeAgent 内核编解码层（C 实现）
|
||
*
|
||
* ============================ 接口冻结声明 ============================
|
||
* 本头文件是对外契约。函数签名、语义、返回值一经发布即为冻结接口，
|
||
* 修改必须走大版本流程（与 third_party/homeagent-sdk 同一冻结标准）。
|
||
*
|
||
* 设计约束（见 docs/zh/c-core/llm-orchestration-c.md §四）：
|
||
* 1. 只吃 const char* + **显式长度**，出数值/字节偏移 —— 不回调 Go、
|
||
* 不传 Go 指针、不要求 NUL 结尾
|
||
* 2. **不 malloc**：不需要出参缓冲区，需要「结果」时返回字节偏移/长度，
|
||
* 由调用方在自己的缓冲上切片（零拷贝）
|
||
* 3. 无状态、纯函数、线程安全（不写全局可变状态）
|
||
*
|
||
* 当前覆盖：L1 协议编解码层中的纯计算部分（第一个最小切片）。
|
||
*
|
||
* ============================ 为什么签名带长度 ============================
|
||
* 初版签名用 `const char*` 隐含「NUL 结尾」，于是每次调用都要：
|
||
* Go `C.CString` 分配+拷贝一遍 → C `strlen` 再扫一遍。
|
||
* 实测这部分开销占单次调用的 80% 以上（cgo 边界本身仅 ~30ns，
|
||
* 而初版 ModelContextWindow 实测 175ns）。
|
||
* 改为「指针 + 长度」后，Go 侧用 unsafe.StringData 直接传底层数组，
|
||
* 零分配零拷贝。这是设计约束第 1 条的字面要求。
|
||
*/
|
||
|
||
#include <stddef.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* ==================== 模型上下文窗口推断 ==================== */
|
||
|
||
/* 无法从模型名推断时的哨兵值（与 Go 侧一致）。
|
||
*
|
||
* 为什么返回哨兵而不是直接给兜底值：调用方需要区分「真推断出了」与
|
||
* 「推断不出、只能兜底」——后者要打一行日志（窗口被低估必须可见），
|
||
* 并提示部署方用 per-source context_window 显式声明。
|
||
* 若 C 侧直接返回兜底值，调用方就永远分不清这两种情况。 */
|
||
#define HA_CODEC_CONTEXT_WINDOW_UNKNOWN (-1)
|
||
|
||
/* 由模型名推断最大上下文窗口（token 数）；推断不出返回
|
||
* HA_CODEC_CONTEXT_WINDOW_UNKNOWN。
|
||
*
|
||
* model 为 UTF-8 字节序列，**不需要 NUL 结尾**；model_len 是字节数。
|
||
* model 为 NULL 或 model_len 为 0 时返回 UNKNOWN。
|
||
*
|
||
* 匹配大小写不敏感（仅对 ASCII 字母做折叠；非 ASCII 字节按原样比较，
|
||
* 与 Go 侧对模型名的实际输入一致）。
|
||
*
|
||
* 语义必须与 Go 侧 modelContextWindowPure 逐值一致（黄金对照测试钉死）。 */
|
||
int ha_codec_model_context_window(const char *model, size_t model_len);
|
||
|
||
/* ==================== token 估算与截断 ==================== */
|
||
|
||
/* 粗略估算 token 数。
|
||
*
|
||
* 规则（与 Go 侧 EstimateTokens 一致）：保守取 max(1, runeCount * 2)。
|
||
* 按 UTF-8 **字符数**（rune）计，不是字节数。
|
||
* text 为 NULL 或 text_len 为 0 返回 0。
|
||
*
|
||
* 非法 UTF-8 序列按 Go 的 utf8 解码语义处理（每字节一个 rune），
|
||
* 保证与 Go 侧逐值一致。 */
|
||
int ha_codec_estimate_tokens(const char *text, size_t text_len);
|
||
|
||
/* 按 token 预算计算「应保留的字节数」。
|
||
*
|
||
* ★ 返回的是**字节数**而非字符串：截断结果必然是输入的前缀，
|
||
* 调用方直接在自己的缓冲上切片即可（零拷贝、无出参缓冲区、无 malloc）。
|
||
*
|
||
* 语义与 Go 侧 TruncateByTokens 一致：从开头保留 maxTokens/2 个 rune；
|
||
* 未超预算时返回 text_len（即整串）。
|
||
* max_tokens <= 0 或 text 为 NULL/text_len 为 0 时返回 0。
|
||
*
|
||
* 返回值保证 <= text_len。 */
|
||
size_t ha_codec_truncate_by_tokens(const char *text, size_t text_len,
|
||
int max_tokens);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* HA_CODEC_H */
|