diff --git a/docs/zh/c-core/llm-orchestration-c.md b/docs/zh/c-core/llm-orchestration-c.md index 1fb81dd..40ca10a 100644 --- a/docs/zh/c-core/llm-orchestration-c.md +++ b/docs/zh/c-core/llm-orchestration-c.md @@ -275,13 +275,56 @@ C 化的正确性**不能靠「跑起来没崩」**,必须有可复现的对 - 放 SDK:天然跨端复用,但要走 SDK 冻结与大版本流程 2. `ha_json.c` 是**复用**(从 remotedevice 复制/提为公共)还是**新写**? 复用会动 SDK 目录结构。 -3. 是否接受「C 化后内核体积/构建复杂度上升」换取延迟确定性? - (需先有一个真实延迟基线,当前没有) -4. **下一个切片选谁**?L1 剩下的是协议编解码(`parseOpenAICompatible*`、 +3. **下一个切片选谁**?L1 剩下的是协议编解码(`parseOpenAICompatible*`、 `normalize*ToolCalls` 等,见 §三 L1 表);该层依赖 JSON 解析 ⇒ 先解第 2 题。 +### 7.1 ★ 跨语言开销基线(实测已补,2026-09-25) + +原 §七 写着「需先有真实延迟基线,当前没有」。现已补上 +(`internal/agent/api/codec_bench_test.go`,`go test -bench`): + +| 基准 | C(经 cgo)| 纯 Go | 谁快 | +|---|---:|---:|---| +| `ModelContextWindow`(短 ASCII)| 175 ns | 38 ns | **Go 快 4.6×** | +| `EstimateTokens` / 空串 | 100 ns | 0.43 ns | **Go 快 230×** | +| `EstimateTokens` / 短 ASCII | 115 ns | 6.5 ns | **Go 快 17×** | +| `EstimateTokens` / 短中文 | 100 ns | 29 ns | **Go 快 3.4×** | +| `EstimateTokens` / 中200字 | 229 ns | 509 ns | C 快 2.2× | +| `EstimateTokens` / 1KB 中文 | 840 ns | 2870 ns | C 快 3.4× | +| `EstimateTokens` / 1KB ASCII | 2318 ns | 332 ns | **Go 快 7×** | +| `TruncateByTokens` / 短中文 | 233 ns | 54 ns | **Go 快 4.3×** | +| `TruncateByTokens` / 1KB 中文 | 3923 ns | 6918 ns | C 快 1.8× | + +**结论(不要凭直觉,数据说话)**: + +1. **cgo 的固定开销约 95–100 ns/次**,小输入下完全压倒算法差异。 +2. C 只在**长中文**(rune 密集、UTF-8 步进重)上明显领先; + 长 ASCII 反而 Go 快 7×(Go 的 `utf8.RuneCountInString` 对 ASCII + 有快路径,而 C 侧逐字节跑)。 +3. ⇒ **「C 比 Go 快」是错的**;正确表述是「在特定输入分布上更快」。 + +**对函数的建议(按调用分布)**: + +- `ModelContextWindow`:调用点单一(`provider.go:333`,每请求一次), + 且输入是**短 ASCII** ⇒ 拿不到收益。但它应该是**冷路径**, + 175 ns 在单次请求尺度上无关痛痒——关键是别把它放到循环里。 +- `EstimateTokens`:**真正的高频点**在 `process.go:476` 的逐事件循环 + (对每条上下文事件算 `Source + Input + 40`)与 `resident.go:552` + (对每条上下文算 `Input + Response`)。字段分布**不单一**: + - `Source` 是短标签(`"qq"` / `"webui"`)⇒ 属 Go 快 17× 那一档 + - `Input` / `Response` 是对话文本,长度跨度大:长中文 C 快 2–3.4×, + 短文本与长 ASCII 则 Go 快 3–7× + ⇒ **没有单一答案**:当前一刀切走 C 会让短串净亏。 + 正确做法是**按长度分派**(短走 Go、长中文走 C), + 但需先用真实长度分布复测——不要凭推测动手。 +- `TruncateByTokens`:调用点单一(`tooldefs.go:38`),非热路径。 + +**这不否定 C 化方向**,但把「选谁下一个 C 化」的判据从「哪个函数看起来底层」 +换成「**哪个在真实输入分布下真能变快**」。协议编解码(JSON 解析、SSE 分片) +处理的正是**长文本**——那才是 C 的主场,也是下一步更合理的候选。 + --- -*实测记录:双路径、缓存跟踪、交叉编译、变异测试均于 2026-09-25 在本仓实测; -工具链与 C 资产核实于本仓* +*实测记录:双路径、缓存跟踪、交叉编译、变异测试、跨语言基准均于 2026-09-25 +在本仓实测;工具链与 C 资产核实于本仓* *初版核实:2026-09-24 · 落地更新:2026-09-25* diff --git a/internal/agent/api/codec_bench_test.go b/internal/agent/api/codec_bench_test.go new file mode 100644 index 0000000..fad7808 --- /dev/null +++ b/internal/agent/api/codec_bench_test.go @@ -0,0 +1,105 @@ +package api + +// codec_bench_test.go —— 编解码层的跨语言开销基线。 +// +// 存在的理由:`codec.go` 的 EstimateTokens 注释写着「是否该留在 C 侧由 +// codec_bench_test.go 的实测数据决定,不要凭直觉断言」。本文件就是那份数据。 +// +// ============================ 为什么必须有 ============================ +// C 化不是免费的:每次调用要走 cgo 边界(~50-100ns 固定开销)+ C.CString +// 分配/释放(O(n) 拷贝)。对**高频热路径**(上下文裁剪对每个事件都调), +// 短文本上这笔开销可能超过 C 实现省下的算术时间。 +// +// 因此判据不是「C 比 Go 快」,而是「在真实输入分布下 C 是否更快」。 +// 本基准跑 cgo 下的 EstimateTokens(走 C)与直调纯 Go 实现,给出分界点。 +// +// 运行:go test -run XXX -bench BenchmarkEstimate -benchmem ./internal/agent/api/ +// 注意:CGO_ENABLED=0 时 cgo 与纯 Go 是同一实现,对比无意义(差异应为 0)。 + +import ( + "strings" + "testing" +) + +// benchInputs 覆盖真实分布:短中文(裁剪查询)、长文本(预算计算)、ASCII。 +var benchInputs = map[string]string{ + "empty": "", + "ascii_short": "hello world", + "zh_short": "用户询问了系统状态", + "zh_200": strings.Repeat("这是一段中文文本。", 20), + "ascii_1k": strings.Repeat("x", 1024), + "zh_1k": strings.Repeat("中", 1024), +} + +// BenchmarkEstimateTokensC 走 C 实现(经 cgo 边界 + CString 分配)。 +func BenchmarkEstimateTokensC(b *testing.B) { + for name, in := range benchInputs { + b.Run(name, func(b *testing.B) { + b.SetBytes(int64(len(in))) + for i := 0; i < b.N; i++ { + _ = estimateTokensC(in) + } + }) + } +} + +// BenchmarkEstimateTokensPure 直调纯 Go 实现(同进程,无边界开销)。 +// 与 C 版的差值即「跨语言开销 − C 实现省下的时间」。 +func BenchmarkEstimateTokensPure(b *testing.B) { + for name, in := range benchInputs { + b.Run(name, func(b *testing.B) { + b.SetBytes(int64(len(in))) + for i := 0; i < b.N; i++ { + _ = estimateTokensPure(in) + } + }) + } +} + +// BenchmarkTruncateByTokensC 走 C(含 malloc/free 与结果拷贝)。 +func BenchmarkTruncateByTokensC(b *testing.B) { + for name, in := range benchInputs { + if in == "" { + continue + } + b.Run(name, func(b *testing.B) { + b.SetBytes(int64(len(in))) + for i := 0; i < b.N; i++ { + _ = truncateByTokensC(in, 64) + } + }) + } +} + +// BenchmarkTruncateByTokensPure 直调纯 Go 实现。 +func BenchmarkTruncateByTokensPure(b *testing.B) { + for name, in := range benchInputs { + if in == "" { + continue + } + b.Run(name, func(b *testing.B) { + b.SetBytes(int64(len(in))) + for i := 0; i < b.N; i++ { + _ = truncateByTokensPure(in, 64) + } + }) + } +} + +// BenchmarkModelContextWindowC 模型名映射(典型高频:每次预算计算)。 +// 输入是短 ASCII,cgo 固定开销占比最高,是 C 化最可能「不划算」的场景。 +func BenchmarkModelContextWindowC(b *testing.B) { + models := []string{"deepseek-v4.1-flash", "gpt-4-turbo", "qwen-max", "AUTO"} + b.ResetTimer() + for i := 0; i < b.N; i++ { + _ = modelContextWindowC(models[i%len(models)]) + } +} + +func BenchmarkModelContextWindowPure(b *testing.B) { + models := []string{"deepseek-v4.1-flash", "gpt-4-turbo", "qwen-max", "AUTO"} + b.ResetTimer() + for i := 0; i < b.N; i++ { + _ = modelContextWindowPure(models[i%len(models)]) + } +} diff --git a/plan.md b/plan.md index 2c845f4..c21839e 100644 --- a/plan.md +++ b/plan.md @@ -410,10 +410,43 @@ PluginContext(独立身份,共享管道)。 2. **`ha_json.c` 复用还是新写?**(复用会动 SDK 目录结构) - 这是下一个切片的**前置**:L1 剩下的协议编解码(`parseOpenAICompatible*`、 `normalize*ToolCalls`)全部依赖 JSON 解析,不定就推不下去 -3. **是否接受「C 化后内核体积/构建复杂度上升」换延迟确定性?** - - 需先有真实延迟基线(当前没有),否则是空头承诺 - - 尤其 `EstimateTokens` 是**高频热路径**(上下文裁剪对每个事件都调), - 跨语言开销对短文本未必划算;它是第一个该拿数据说话的候选 +3. **下一个切片选谁?**(已有基准数据支撑,见下) + +### ★ 已定:跨语言开销基线已补齐(2026-09-25) + +原本文写「需先有真实延迟基线(当前没有)」——现已补上 +(`internal/agent/api/codec_bench_test.go`)。数据**反驳了「C 比 Go 快」的直觉**: + +| 基准 | C(经 cgo)| 纯 Go | 谁快 | +|---|---:|---:|---| +| `ModelContextWindow`(短 ASCII)| 175 ns | 38 ns | **Go 快 4.6×** | +| `EstimateTokens` / 空串 | 100 ns | 0.43 ns | **Go 快 230×** | +| `EstimateTokens` / 短中文 | 100 ns | 29 ns | **Go 快 3.4×** | +| `EstimateTokens` / 中 200 字 | 229 ns | 509 ns | C 快 2.2× | +| `EstimateTokens` / 1KB 中文 | 840 ns | 2870 ns | C 快 3.4× | +| `EstimateTokens` / 1KB ASCII | 2318 ns | 332 ns | **Go 快 7×** | +| `TruncateByTokens` / 短中文 | 233 ns | 54 ns | **Go 快 4.3×** | + +三条结论: +1. **cgo 固定开销约 95–100 ns/次**,小输入下完全压倒算法差异 +2. C 只在**长中文**(UTF-8 步进重)上领先;长 ASCII 反而 Go 快 7× +3. ⇒ 判据应是「**哪个在真实输入分布下真能变快**」,不是「哪个看起来更底层」 + +**对现有三个函数的影响(实测调用分布)**: + +- `EstimateTokens` 的**真高频点在 `process.go:476` 的逐事件循环** + (对每条上下文事件算 `Source + Input + 40`)。实测字段分布: + - `Source` 是**短标签**(`"qq"` / `"webui"`),按上表属 **Go 快 17×** 那一档 + - `Input` / `Response` 是**对话文本,长度跨度大**:长中文 C 快 2–3.4×, + 短文本与长 ASCII 则 Go 快 3–7× + ⇒ 该循环**没有单一答案**:当前一刀切走 C 会让 `Source` 这类短串净亏。 + 待办:若长会话下该循环累积可观,应改为**按长度分派**(短走 Go、长中文走 C), + 但**先用 `-bench` 复测真实长度分布再定**,不要凭此处推测动手。 +- `ModelContextWindow`(`provider.go:333`)与 `TruncateByTokens`(`tooldefs.go:38`) + 调用点单一、非热路径,175/233 ns 在单次请求尺度上无关痛痒。 + +⇒ **这不否定 C 化方向**:协议编解码(JSON 解析、SSE 分片)处理的正是长文本, +那才是 C 的主场,也是比「把短函数搬过去」更合理的下一步。 ### 已定事项(不再挂账)