跳转到内容
For the complete documentation index, see llms.txt. This page is also available as Markdown.

智能令牌压缩

TokenJuice 会在冗长的工具输出进入模型上下文前进行压缩,同时保留可恢复的完整原始内容。

LLM 令牌要花钱,而冗长的工具输出会浪费掉其中大部分。A git status 在一个繁忙的仓库里, cargo build 日志、一个 600 条消息的邮件线程和一个 docker ps -a 与真实集群对比时,任何一个都可能几乎不提供任何信息,却占满上下文窗口。

OpenHuman 随附 TokenJuice,这是 agent 工具执行路径中的一个压缩路由器。在工具结果到达模型之前,编译后的 TinyJuice 模块会对其进行分类,选择压缩器,在需要时将可恢复的原始内容存入其 CCR 缓存,并返回压缩后的结果。该模块负责压缩、CCR 检索与查询、HTML 提取,以及以下中的 schema 和请求/结果类型 tinyjuice-bus。OpenHuman 提供配置、文件系统授权、按回合限制的模型调用以及节省归因。命令和日志规则来自 vincentkoc/tokenjuice.

流水线

每个工具结果都会通过 TinyJuice 模块的路由器走相同的路径:

原始工具结果
        │
        ▼
1. 大小门槛          路由器已启用?输入 ≥ min_bytes_to_compress(2 KB)?
        │  是
        ▼
2. 检测类型        Json · Diff · Html · Search · Code · Log · PlainText
        │
        ▼
3. 选择压缩器      每种类型一个专用压缩器(+ 每种类型开关)
        │
        ▼
4. 压缩            运行它;如果它拒绝或使输出变大,则回退/直接透传
        │
        ▼
5. CCR 资格        有损 AND ≥ ccr_min_tokens(约 500)?→ 将原始内容卸载到缓存
        │
        ▼
6. 附加标记        ⟦tj:<hash>⟧ 页脚,以便 agent 可以取回完整原文
        │
        ▼
7. 记录节省        按模型和压缩器记录节省的令牌 + 成本
        │
        ▼
   压缩后的文本 → LLM 上下文
  1. 大小门槛。 如果路由器关闭,或者输入低于 min_bytes_to_compress (默认 2048 字节),则会原样透传。太小的输出不值得压缩。

  2. 内容检测 (detect/kind.rs)。结果会被分类为七种类型之一。优先级顺序是:显式提示,其次是 MIME 或扩展名标记,然后是按工具的先验(例如 grep 表示 Search, git_operations 表示 Diff, run_tests 表示 Log),然后是廉价的结构启发式(JSON、Diff、HTML、Search、Code、Log、PlainText)。热路径上没有正则。

  3. 压缩器选择。 每种类型都会进入自己的压缩器,并遵守按类型的开关(search_enabled, code_enabled, html_enabled).

  4. 压缩。 压缩器运行。如果它拒绝,或者其输出不比输入更小,TokenJuice 就会回退到通用压缩器,或者直接透传原文。它绝不会让内容变得更大。

  5. CCR 卸载。 当压缩是有损的,而且原文足够大(ccr_min_tokens,默认约 500 个令牌)时,完整原文会进入 Compress-Cache-Retrieve(CCR)存储,因此不会永久丢失。

  6. 恢复标记。 会附加一个带有标记 ⟦tj:<hash>⟧ 的页脚。它会告诉 agent 这个视图只是部分内容,以及如何获取剩余部分。

  7. 节省记账。 按模型和压缩器记录已节省的令牌数和估算节省成本。

这些压缩器

每种内容类型都有一个专用压缩器(vendor/tinyjuice/src/compressors/):

压缩器
类型
作用

SmartCrusher

JSON

将对象数组重新渲染为紧凑表格。超过大约 40 行后,会保留开头、结尾、错误行和数值异常值。

Code

Code

保留签名和导入,并将深层函数体折叠为 { … N 行 … } (可用时使用 tree-sitter,否则使用大括号深度启发式)。保留 TODO, FIXME, error, panic 和 unsafe 标记。

Log

Log

对于命令输出,使用 JSON 规则引擎(见下文)。对于其他日志,则保留错误、警告、堆栈跟踪和摘要,并丢弃噪声。

Search

Search

将 grep 和 ripgrep path:line:body 命中按文件分组,按查询词密度排序,保留每个文件的最佳匹配,并统计 [+N more].

Diff

Diff

保留变更行和 hunk 标头,并将很长的未变更片段折叠为锚点。锁文件的 hunk 会缩成一行 +A/-B 摘要。

Html

HTML

去除标记,转换为可读文本,采用合理的块边界换行和实体解码(占用少,且不构建 DOM)。

TextCrusher

PlainText

确定性的显著性压缩,保留句子和段落边界。

通用

回退

适用于没有任何特定规则匹配的命令输出的首尾摘要。对于结构化结果它会拒绝,以便保留原样。

多字节文本(CJK、emoji、组合标记)会按字素逐个处理,绝不会在字符中间拆分。

句柄预览和 juice 工具(默认)

默认启用压缩。对于至少 ccr_min_tokens的结果,该模块会将原文存入其 CCR 缓存,并向模型显示一个小预览,而不是压成一个整体:

  • 一行统计描述其形状(估算令牌数、字节数、行数、JSON 键,或 Markdown 大纲;绝不包含值),

  • 前 500 个字符,

  • 一个抽取式大纲,以及

  • 一个标注句柄(CCR 令牌)的页脚。

然后,模型通过三个只读工具查询已存储的原文,这些工具都不会调用模型:

工具
作用

juice_find

文本, grep, 正则, 排序 (BM25), sed, awk 和 jq 对输出进行操作,并带有类似 Python 的 作用域 切片。

juice_extract

HTML 或 Markdown 输出中的链接或标题。

juice_summarize

大小、大纲或 JSON 结构,然后是开头和结尾,或者与某个 提示.

答案有大小上限,未知或已被驱逐的句柄会报错。 juice_retrieve 仍然会返回完整原文。句柄预览是在不调用模型的情况下构建的,因此对于大到足以生成摘要的结果,它也会替代 LLM 摘要。缓慢的摘要器不会阻塞当前回合。这三个只读工具由 tinyjuice-bus 声明,并在该模式开启时为新会话注册;已恢复的会话会保留其转录中记录的声明。它们的宿主适配器会向模块发送类型化查询;不会读取模块缓存,也不会在本地重复其查询算法。对于工件路径,OpenHuman 会先应用其常规路径和大小检查,然后在不发送路径的情况下,将已授权内容发送给模块。

每次对话都会记录模型的工具目录,并在该线程恢复时保持冻结。如果转录中包含 Juice 工具,OpenHuman 会恢复其记录的名称和 schema,即使当前设置本不会创建新句柄。恢复后的工具仍使用当前宿主路径授权和模块策略。被禁用或不可用的模块对查询会返回明确的不可用结果;OpenHuman 不会用本地 CCR 存储或查询实现替代它。可选的输出压缩会保持其既有的 fail-open 行为:当模块无法压缩时,会返回未修改的结果。

要关闭整个功能,请设置 context.compaction_enabled = false 或者 OPENHUMAN_COMPACTION=0。要保留压缩但回到单块压缩和 juice_retrieve,请设置 tokenjuice.repl_handle_enabled = false (OPENHUMAN_TOKENJUICE_REPL_HANDLE_ENABLED=0).

不会丢失任何内容:CCR 缓存

有损压缩通常会丢弃数据。TinyJuice 则会把完整原文存入模块拥有的 CCR 存储,并留下一个线索。

  • 内存层 (始终开启):模块的存储以 SHA-256 哈希为键,并受条目数(max_cache_entries,默认 256)和总字节数(max_cache_bytes,默认 64 MiB)限制,并采用 FIFO 淘汰。

  • 磁盘层 (可选): <workspace>/.tokenjuice/ccr/,通过 ccr_disk_enabled启用。它可在内存淘汰后继续保留。可通过 ccr_ttl_secs.

  • 标记: 压缩后的输出以如下页脚结尾 [compacted tool output: PARTIAL view; full original available via juice_retrieve with token "…"] 携带 ⟦tj:<hash>⟧ 令牌。

  • 检索工具: agent 使用只读的 juice_retrieve 带着该令牌调用该工具(可选地附带字节或行 范围)即可获取完整原文或其切片。该令牌是不可猜测的 SHA-256 摘要。

默认情况下,agent 先获得廉价的压缩视图,只有在需要时才会放大查看完整文本。

节省跟踪

OpenHuman 的节省回调会对每次压缩进行计量(crates/openhuman-core/src/inference/tokenjuice/savings.rs)。TokenJuice 会报告事件和令牌差值。OpenHuman 会应用已配置的默认模型输入定价,汇总 总计, 按模型 和 按压缩器,而模块会将统计信息保存到其 juice.savings 存储文档中(旧的 <workspace>/state/tokenjuice_savings.json 仅会导入一次)。

可通过 RPC 读取它们: openhuman.tokenjuice_savings_stats;可通过以下命令清除它们: openhuman.tokenjuice_savings_reset.

规则覆盖层(命令和日志输出)

一个三层 JSON 规则覆盖层驱动日志和命令压缩器。规则按顺序合并,后面的层会覆盖前面的层:

层
路径
用途

内置

随二进制一起提供

大约 96 条随附规则,适用于 git、npm、cargo、docker、kubectl、ls 等

用户

~/.config/tokenjuice/rules/

适用于所有位置的个人覆盖

项目

.tokenjuice/rules/

特定仓库的覆盖,已提交并与团队共享

每条规则都会命名一个命令或工具模式,以及一种缩减策略:跳过并保留过滤器、诸如 strip-ANSI 和 dedupe 的转换、首尾摘要、命名计数器和预设消息。规则是 JSON。添加一条即可生效,无需重新编译。

配置、RPC 和工具

所有内容都位于 [tokenjuice] 配置块中(crates/openhuman-core/src/config/schema/tokenjuice.rs),并且可以实时更改。

  • 总开关: context.compaction_enabled (默认 true; OPENHUMAN_COMPACTION=0 表示选择退出)以及 router_enabled (默认 true).

  • 句柄预览: repl_handle_enabled (默认 true).

  • 阈值: min_bytes_to_compress 和 ccr_min_tokens.

  • CCR: ccr_enabled, ccr_disk_enabled, max_cache_entries, max_cache_bytes 和 ccr_ttl_secs.

  • 按类型: search_enabled, code_enabled, html_enabled.

  • RPC(openhuman.tokenjuice_*): detect, compress (对流水线做 dry-run), settings_get 和 settings_update (在线部分补丁), cache_stats, retrieve, savings_stats 和 savings_reset.

  • Agent 工具: juice_retrieve 恢复整个已存储的原文。 juice_find, juice_extract 和 juice_summarize 按句柄查询一个。全部都是只读。

  • 调试:用以下命令启动 core RUST_LOG=openhuman_core::inference::tokenjuice=debug 即可查看检测、匹配,以及每个结果被裁掉了多少。

这为何重要

agent 的上下文预算就是它的上限。一次工作会话可能会扩展到几十次工具调用:grep、build、测试运行、 git 输出和大量 网页抓取 结果。TokenJuice 会在每个结果进入上下文之前先对其压缩,因此 agent 可以扫过嘈杂仓库或长网页,而不会填满窗口。一次会话中的节省会不断累积,并以美元计量(见 计费、成本和用量).

TokenJuice 运行在 agent 的工具结果上,而不是运行在 内存 摄取上。源同步会自己转换文档,不会把负载通过 TokenJuice 路由。

另见

最后更新于