ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

LlamaIndex QueryEngineTool 深度指南:将查询引擎封装为 Agent 工具的完整实战

LlamaIndex QueryEngineTool 深度指南:将查询引擎封装为 Agent 工具的完整实战 LlamaIndex QueryEngineTool 深度指南将查询引擎封装为 Agent 工具的完整实战【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index导读本指南以 LlamaIndex 核心库中llama_index.core.tools.query_engine模块为骨架系统讲解如何将任意 Query Engine查询引擎封装为可被 Agent 直接调用的工具QueryEngineTool并延伸到带质量评估的EvalQueryEngineTool、工具元数据ToolMetadata、输出结构ToolOutput以及它们在SubQuestionQueryEngine等复合查询引擎中的典型应用。读完本文你将掌握工具化封装的全部关键 API、参数语义、输入解析规则与底层调用链能够把知识库问答能力无缝接入 ReAct 等 Agent 工作流。说明docs/api_reference/api_reference/tools/query_engine.md是使用 mkdocstrings 语法::: llama_index.core.tools.query_engine生成的 API 参考页其完整内容由源码模块 query_engine.py 提供。本文即以此模块及其测试、应用场景为事实依据展开。一、QueryEngineTool 是什么查询引擎与 Agent 之间的适配层在 LlamaIndex 中Query Engine 负责“接收自然语言查询 → 检索索引 → 合成回答”的完整链路而 Agent 需要的是“可被 LLM 理解、按函数签名调用”的工具抽象。QueryEngineTool位于 query_engine.py正是这两者之间的桥梁它继承自AsyncBaseTool定义于 types.py既满足 LlamaIndex 自身 Agent 的工具接口也兼容工具选择ToolSelection等调用机制它持有BaseQueryEngine实例和ToolMetadata元数据LLM 通过元数据中的名称与描述来决定“何时调用、怎样调用”每次调用等价于执行一次query_engine.query(query_str)并把返回的Response包装成统一的ToolOutput。模块级默认值清晰表达了其定位query_engine.pyDEFAULT_NAME query_engine_tool DEFAULT_DESCRIPTION Useful for running a natural language query against a knowledge base and get back a natural language response. 也就是说不显式指定name和description时工具默认名为query_engine_tool默认描述为“对知识库执行自然语言查询并返回自然语言回复”。实际生产环境中强烈建议自定义更精确的描述——因为 LLM 正是依靠描述来判断何时选用该工具的。二、快速上手三行代码把索引变成 Agent 工具以from_defaults工厂方法为入口封装过程最简形式如下from llama_index.core.tools import QueryEngineTool from llama_index.core import VectorStoreIndex index VectorStoreIndex.from_documents(documents) query_engine index.as_query_engine() tool QueryEngineTool.from_defaults( query_enginequery_engine, namedocs_query, description查询公司内部产品文档知识库支持自然语言提问。, )之后即可把tool交给 Agent如ReActAgent、FunctionCallingAgent或直接手动调用# 同步调用 output tool(什么是 LlamaIndex) print(output.content) # 异步调用 output await tool.acall(input什么是 LlamaIndex)工厂方法的完整签名query_engine.pyclassmethod def from_defaults( cls, query_engine: BaseQueryEngine, name: Optional[str] None, description: Optional[str] None, return_direct: bool False, resolve_input_errors: bool True, ) - QueryEngineTool各参数语义如下参数类型默认值作用query_engineBaseQueryEngine必填被包装的查询引擎任意实现了query/aquery的引擎均可索引查询引擎、CustomQueryEngine、复合引擎等namestrquery_engine_tool工具名称Agent 与 LLM 据此引用该工具descriptionstr模块默认描述工具的用途说明是 LLM 决定“是否调用、何时调用”的关键信号return_directboolFalse若为True工具返回结果将直接作为 Agent 最终回复不再进入后续推理循环resolve_input_errorsboolTrue输入参数不匹配时是否容错解析详见第五节三、核心调用链call / acall 如何执行一次查询QueryEngineTool实现了AsyncBaseTool的两个核心方法query_engine.pydef call(self, *args: Any, **kwargs: Any) - ToolOutput: query_str self._get_query_str(*args, **kwargs) response self._query_engine.query(query_str) return ToolOutput( contentstr(response), tool_nameself.metadata.get_name(), raw_input{input: query_str}, raw_outputresponse, ) async def acall(self, *args: Any, **kwargs: Any) - ToolOutput: query_str self._get_query_str(*args, **kwargs) response await self._query_engine.aquery(query_str) return ToolOutput( contentstr(response), tool_nameself.metadata.get_name(), raw_input{input: query_str}, raw_outputresponse, )从中可以看到完整的底层调用链_get_query_str(*args, **kwargs)从调用参数中提取查询字符串同步路径调用query_engine.query(query_str)异步路径调用query_engine.aquery(query_str)结果被封装为ToolOutput其中content为str(response)响应文本供 LLM 直接阅读tool_name为工具元数据中的名称raw_input记录原始查询输入raw_output保留完整Response对象含source_nodes等结构化信息可供后处理或评估器使用。query_engine和metadata均以只读 property 暴露query_engine.py便于外部获取底层引擎与元数据。四、输入解析规则_get_query_str的三种匹配路径工具被 LLM 或手动调用时参数形态并不总是标准化的。_get_query_strquery_engine.py按优先级处理三种情况def _get_query_str(self, *args: Any, **kwargs: Any) - str: if args is not None and len(args) 0: query_str str(args[0]) # 1) 位置参数 elif kwargs is not None and input in kwargs: query_str kwargs[input] # 2) input 关键字参数 elif kwargs is not None and self._resolve_input_errors: query_str str(kwargs) # 3) 容错整体转字符串 else: raise ValueError( Cannot call query engine without specifying input parameter. ) return query_str三种路径逐一说明位置参数tool(hello world)直接把第一个位置参数作为查询串input关键字tool(inputfoo)—— 这是默认函数签名DefaultToolFnSchema的标准字段见第六节也是 Agent 函数调用场景下最常见的形态容错解析当传入tool(tmphello)这类未匹配参数时若resolve_input_errorsTrue会整体转成字符串{tmp: hello}交给查询引擎避免工具调用崩溃若resolve_input_errorsFalse则抛出ValueError。这一容错行为在单元测试 test_query_engine_tool.py 中有完整覆盖测试同时验证了位置参数、input关键字、按fn_schema生成的参数字典、以及resolve_input_errors开启/关闭两种场景下的行为。五、ToolMetadataLLM 眼中的工具说明书每个工具都携带一个ToolMetadata实例定义于 types.pydataclass class ToolMetadata: description: str name: Optional[str] None fn_schema: Optional[Type[BaseModel]] DefaultToolFnSchema return_direct: bool False默认函数签名DefaultToolFnSchema只有一个字段class DefaultToolFnSchema(BaseModel): Default tool function Schema. input: str即默认情况下LLM 眼中的该工具就是一个“只接受一个input字符串参数”的函数。这解释了为什么_get_query_str专门兼容input关键字。ToolMetadata还负责把工具描述转换成 LLM 供应商可识别的 JSON Schemaget_parameters_dict()types.py基于fn_schema.model_json_schema()生成参数声明fn_schema为None时退化为{input: input query string, type: string}的兜底结构to_openai_tool()types.py生成 OpenAI 风格的{type: function, function: {...}}工具描述并做两项校验描述超过 1024 字符会抛出ValueError名称通过_sanitize_name清洗为只含[a-zA-Z0-9_-]的合法函数名旧版to_openai_function()已被标记deprecated应改用to_openai_tool。六、ToolOutput统一的工具输出结构ToolOutputtypes.py是所有工具的标准化返回类型class ToolOutput(BaseModel): blocks: List[ContentBlock] # 内容块列表含文本块 tool_name: str raw_input: Dict[str, Any] raw_output: Any is_error: bool False构造时content字符串会被自动包装为TextBlock且content与blocks不能同时传入否则抛ValueError。content属性则将多个文本块拼接为纯文本方便 Agent 直接消费。七、进阶EvalQueryEngineTool——带质量评估闸门的工具EvalQueryEngineTool继承自QueryEngineTool实现于 eval_query_engine.py它在查询后追加一步回答相关性评估只有评估通过工具结果才会原样返回评估失败则把内容替换为失败模板FAILED_TOOL_OUTPUT_TEMPLATE ( Could not use tool {tool_name} because it failed evaluation.\nReason: {reason} )关键点from_defaults中未显式传入evaluator时默认使用AnswerRelevancyEvaluatoreval_query_engine.pycall/acall在父类执行后调用evaluator.evaluate_response(query, response)依据EvaluationResult.passing决定放行还是替换输出eval_query_engine.py评估者本身可以是任意BaseEvaluator实现例如自定义的基于 LLM 的评估器。使用示例from llama_index.core.tools.eval_query_engine import EvalQueryEngineTool eval_tool EvalQueryEngineTool.from_defaults( query_enginequery_engine, nameverified_docs_query, description查询知识库且回答必须通过相关性评估。, )其行为在 test_eval_query_engine_tool.py 中通过 mock 评估器分别验证了“评估通过返回原始输出”与“评估失败返回失败模板”两条路径。这类工具适合对回答质量敏感、需要过滤幻觉式回复的场景。八、典型应用作为子问题路由与复合查询的基础单元QueryEngineTool是多个高级查询引擎的构建单元最典型的当属SubQuestionQueryEnginesub_question_query_engine.py。它的工作机制是LLM 依据各工具元数据把复杂查询拆解为多个子问题question_gen 阶段每个子问题交给对应的QueryEngineTool执行self._query_engines以tool.metadata.name为键保存引擎映射汇总所有子问题答案与来源节点交给response_synthesizer合成最终回答。典型用法sub_question_query_engine.pyfrom llama_index.core.query_engine import SubQuestionQueryEngine from llama_index.core.tools import QueryEngineTool tool1 QueryEngineTool.from_defaults( query_engineengine_a, nameengine_a, description回答关于文档A的问题 ) tool2 QueryEngineTool.from_defaults( query_engineengine_b, nameengine_b, description回答关于文档B的问题 ) engine SubQuestionQueryEngine.from_defaults( query_engine_tools[tool1, tool2], use_asyncTrue, ) response engine.query(比较文档A与文档B中的方案差异)类似的组合还出现在RouterQueryEnginerouter_query_engine.py、SQL 向量联合查询等场景中QueryEngineTool因而成为跨引擎编排的通用“接口单元”。上述所有工具类统一从llama_index.core.tools包导出见 tools/init.py使用时直接from llama_index.core.tools import QueryEngineTool即可。九、与 LangChain 互操作as_langchain_toolQueryEngineTool提供as_langchain_tool()方法query_engine.py可将其转换为 LangChain 的LlamaIndexTooldef as_langchain_tool(self) - LlamaIndexTool: from llama_index.core.langchain_helpers.agents.tools import ( IndexToolConfig, LlamaIndexTool, ) tool_config IndexToolConfig( query_engineself.query_engine, nameself.metadata.get_name(), descriptionself.metadata.description, ) return LlamaIndexTool.from_tool_config(tool_configtool_config)转换过程中保留查询引擎、工具名称与描述使你可以在 LangChain 的 Agent 体系中复用同一个 LlamaIndex 查询引擎。十、设计要点回顾与最佳实践结合源码与测试总结QueryEngineTool的使用要点名称与描述是工具的灵魂LLM 依赖description判断工具适用场景务必写清“查询什么数据、何时使用”名称保持唯一且仅含字母、数字、下划线、连字符默认签名为单一input字符串无需自定义fn_schema即可被函数调用型 Agent 正确调用若要扩展参数可自定义fn_schemaBaseModel子类传入ToolMetadatareturn_direct控制是否结束推理对“查询即答案”的简单检索置为True可减少一次多余的 LLM 生成resolve_input_errors决定容错策略默认开启可避免参数不匹配导致工具崩溃代价是查询串可能包含额外噪音追求严格性时关闭并依赖ValueError快速失败同步/异步一致调用Agent 异步执行时走acall→aquery同步时走call→query两条路径输出结构完全一致质量敏感场景叠加评估EvalQueryEngineTool可在回答进入 Agent 上下文前完成相关性过滤配合failed_tool_output_template自定义失败反馈。十一、进一步阅读工具基类与元数据定义tools/types.py查询引擎工具核心实现tools/query_engine.py带评估的查询引擎工具tools/eval_query_engine.py单元测试输入解析与容错tests/tools/test_query_engine_tool.py单元测试评估闸门tests/tools/test_eval_query_engine_tool.py子问题查询引擎应用示例query_engine/sub_question_query_engine.py工具包统一导出入口tools/init.py【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表