后处理工具输出¶

ToolUniverse 的智能输出处理

ToolUniverse Hooks 系统提供对工具输出的自动后处理功能。使用 Hooks 可对长结果进行摘要，将大量输出保存到文件中，并根据具体工具或工作流程自定义行为。

什么是钩子（Hooks）？¶

Hooks 是一种后处理函数，可在工具输出返回给您之前自动对其进行转换。它们的设计目的包括：

总结长输出：使用人工智能将冗长的结果浓缩为关键洞察
保存大型数据集：将大量输出作为带有元数据的文件存储
自定义处理：根据工具类型或输出尺寸应用不同的逻辑
提升性能：减少内存使用和处理时间

快速入门¶

通过一行代码启用钩子：

from tooluniverse import ToolUniverse

# Enable default SummarizationHook
tu = ToolUniverse(hooks_enabled=True)
tu.load_tools()

# Run tools - outputs are automatically processed
result = tu.run({
    "name": "OpenTargets_get_target_gene_ontology_by_ensemblID",
    "arguments": {"ensemblId": "ENSG00000012048"}
})

选择不同的钩子类型：

# Use FileSaveHook for large outputs
tu = ToolUniverse(hooks_enabled=True, hook_type='FileSaveHook')

# Use custom configuration
tu = ToolUniverse(hooks_enabled=True, hook_config=my_config)

Hook Types¶

SummarizationHook - 基于AI的摘要功能: 自动使用先进的人工智能模型对冗长的工具输出进行总结，在缩短长度的同时保留关键结果。
FileSaveHook - 基于文件的处理: 将大型输出保存到磁盘并附加元数据。返回文件信息而非原始输出。
自定义钩子 - 用户定义的处理: 创建您自己的钩子以满足特殊处理需求。

何时使用钩子¶

使用 SummarizationHook 的场景： - 工具输出内容过长，难以高效阅读 - 需要从详细数据中快速获取洞察 - 处理文献搜索结果 - 处理大型科学数据集

Note: Some tools (like Tool_RAG, ToolFinderEmbedding) are automatically excluded from hook processing to prevent information missing. You can customize excluded tools using the exclude_tools configuration option.

使用 FileSaveHook 的场景： - 输出超出内存限制 - 需要将输出作为文件进行处理 - 归档结果以供后续分析 - 与外部工具集成

使用自定义钩子（Custom Hooks）的场景： - 您有特定的处理需求 - 标准钩子无法满足您的需求 - 您需要进行专门的数据转换

性能影响¶

钩子会增加处理开销，但能带来显著的优势：

SummarizationHook：处理时间增加2-5倍，输出减少50-80%
FileSaveHook：极低的开销，显著的内存节省
自定义钩子：取决于实现

权衡通常是值得的，尤其是对于从处理过程中获益的大规模输出。

主题摘要

摘要钩子：自动将冗长的工具输出浓缩为简洁且高效的信息摘要。适用于文献结果、大型数据集及多步骤工作流程。
文件保存钩子：将大型输出及其元数据保存到磁盘，以便后续处理和共享。适用于大容量数据、审计追踪和外部管道。
钩子配置：配置钩子的运行时机、触发条件及行为方式。支持阈值设置、按工具规则及高级选项。
服务器与标准输入输出钩子集成：如何在服务器（HTTP/SSE）和标准输入输出模式中使用钩子。涵盖命令行参数、Python API、默认设置及最佳实践。

示例¶

完整的 Hook 示例：

一个全面展示所有钩子功能的示例可在以下位置查看：

# Run all hook examples
python examples/hooks_example.py

示例功能：

基本用法：简单的SummarizationHook和FileSaveHook示例
高级配置：自定义设置和工具专用挂钩
性能测试：不同钩子配置之间的比较
错误处理：优雅降级与错误恢复