LlamaIndex × Guidance 集成实战用约束式结构化输出生成 Pydantic 对象并加固子问题查询引擎【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南围绕 LlamaIndex 官方社区集成文档 guidance.md 展开系统讲解如何将微软开源的 Guidance 语言嵌入 LlamaIndex利用其强制约束能力让 LLM 直接产出符合 JSON Schema / Pydantic 模型的结构化对象并把这一能力注入SubQuestionQueryEngine的中间环节以提升子问题生成的鲁棒性。读完本文你将掌握GuidancePydanticProgram的完整用法、handlebars 模板转换原理以及GuidanceQuestionGenerator的接入方式。为什么需要 Guidance从建议结构到强制结构常规的 LLM 结构化输出做法是在提示词里请求模型输出一段 JSON再交给解析器处理。这种模式有两个隐患一是模型可能产出畸形 JSON例如缺少括号、字段错位二是解析失败时整个链路报错需要重试或容错逻辑。Guidance 提供了一条不同的路径它把生成generation、提示prompting和逻辑控制logical control交织进同一个连续流程与语言模型实际逐 token 处理文本的方式对齐。最关键的是它可以强制LLM 输出遵循指定 schema 的结构而不是仅仅建议——模型只需专注于内容本身语法层面的错误被彻底排除输出解析问题因此完全消失。这种能力对参数量较小、训练语料中源代码数据不足的弱模型尤其有价值它们难以稳定地生成格式良好、层级正确的结构化输出而 Guidance 的约束机制恰好弥补了这一短板。GuidancePydanticProgram一行代码生成 Pydantic 对象LlamaIndex 将 Guidance 的约束能力封装为GuidancePydanticProgram用于直接产出 Pydantic 对象。该实现位于 program/guidance/base.py继承自核心库中的BaseLLMFunctionProgram见 llm_prompt_program.py其单元测试 test_program_guidance.py 验证了类的继承关系。定义目标 schema假设我们要生成一张专辑包含歌名与时长schema 如下from pydantic import BaseModel from typing import List class Song(BaseModel): title: str length_seconds: int class Album(BaseModel): name: str artist: str songs: List[Song]注意 handlebars 模板约定Guidance 使用 handlebars 风格模板双花括号{{}}用于变量替换单花括号{}表示字面花括号——这与 Python format string 的约定恰好相反Python 中单花括号是变量占位符双花括号才是转义后的字面括号。好在 LlamaIndex 提供了convert_to_handlebars工具函数位于 guidance_utils.py可把 Python format string 风格的提示模板一键转换为 Guidance 的 handlebars 模板。该函数的转换逻辑是先将双花括号替换为临时占位符再把所有单花括号翻倍最后把占位符还原为单花括号从而完成两种约定之间的互转。创建并运行程序from llama_index.program.guidance import GuidancePydanticProgram from guidance.llms import OpenAI as GuidanceOpenAI program GuidancePydanticProgram( output_clsAlbum, prompt_template_strGenerate an example album, with an artist and a list of songs. Using the movie {{movie_name}} as inspiration, guidance_llmGuidanceOpenAI(text-davinci-003), verboseTrue, )然后像调用函数一样传入额外输入运行程序output program(movie_nameThe Shining)得到的就是一个结构完整的AlbumPydantic 对象Album( nameThe Shining, artistJack Torrance, songs[ Song(titleAll Work and No Play, length_seconds180), Song(titleThe Overlook Hotel, length_seconds240), Song(titleThe Shining, length_seconds210), ], )说明GuidancePydanticProgram内部通过user()/assistant()会话块包裹提示并追加gen(stop.)生成调用执行完成后会用parse_pydantic_from_guidance_program从返回文本中提取最后一个 markdown 格式的 JSON 代码块再经model_validate反序列化为目标 Pydantic 对象。由于当前 Guidance 版本尚不支持从Program.variables直接提取嵌套对象源码中对此采用了解析最终文本的临时方案注释中已明确标注详情见 guidance_utils.py。参数要点与 from_defaults 入口output_cls目标 Pydantic 模型类决定强制输出的 schemaprompt_template_strhandlebars 风格的提示模板其中的{{变量}}会在调用时以关键字参数传入guidance_llmGuidance 侧的 LLM 实例例如GuidanceOpenAI(text-davinci-003)若未提供源码中会默认回退到OpenAI(gpt-3.5-turbo)verbose是否打印原始输出便于调试。此外还提供了from_defaults类方法允许以promptPromptTemplate对象或prompt_template_str二选一的方式初始化两者都传或都不传会抛出ValueError。完整的可交互示例见 guidance_pydantic_program.ipynb。底层JSON Schema 到 Guidance 模板的自动转换在 guidance_utils.py 中json_schema_to_guidance_output_template负责把 Pydantic 模型的 JSON Schema 递归转换为 Guidance 约束模板object类型输出字面{...}结构逐字段展开array类型使用{{#geneach ...}}循环块配合stop]与可选的max_iterations对应 schema 的max_items控制列表长度元素间用{{#unless first}}, {{/unless}}插入逗号string类型使用{{gen key stop}}生成带结束符约束的字符串integer/number类型默认同样以stop约束可开启use_pattern_control用pattern[0-9\.]限定数字字符boolean类型使用{{#select key}}True{{or}}False{{/select}}强制二选一。该实现基于微软 guidance 仓库的 jsonformer 思路并扩展支持了嵌套 Pydantic 模型通过$ref解析到$defs。这也解释了为何弱模型也能稳定输出层级正确的 JSON——语法路径已被模板锁死。用 Guidance 加固 SubQuestionQueryEngine 的子问题生成LlamaIndex 提供了一系列高级查询引擎其中不少依赖中间步骤的结构化输出。若中间响应结构不稳定后续解析就会失败。Guidance 正好可以在此处发挥价值确保中间响应具备预期结构从而可被可靠地解析为结构化对象。集成文档给出了一个典型实践实现GuidanceQuestionGenerator并替换SubQuestionQueryEngine默认的问题生成器。其源码位于 question_gen/guidance/base.py对应单元测试见 test_question_gen_guidance_generator.py。from llama_index.question_gen.guidance import GuidanceQuestionGenerator from guidance.llms import OpenAI as GuidanceOpenAI # 定义基于 guidance 的问题生成器 question_gen GuidanceQuestionGenerator.from_defaults( guidance_llmGuidanceOpenAI(text-davinci-003), verboseFalse ) # 定义查询引擎工具 query_engine_tools ... # 构建子问题查询引擎 s_engine SubQuestionQueryEngine.from_defaults( question_genquestion_gen, # 使用上面定义的 guidance 版 question_gen query_engine_toolsquery_engine_tools, )内部实现剖析GuidanceQuestionGenerator继承自核心库的BaseQuestionGenerator其from_defaults内部以SubQuestionList为output_cls构建了一个GuidancePydanticProgram并使用默认子问题提示模板DEFAULT_GUIDANCE_SUB_QUESTION_PROMPT_TMPL convert_to_handlebars( DEFAULT_SUB_QUESTION_PROMPT_TMPL )核心的generate方法会把工具列表序列化为 JSON 文本build_tools_text见 prompts.py连同用户查询一起作为关键字参数传入程序最终返回List[SubQuestion]。默认提示模板DEFAULT_SUB_QUESTION_PROMPT_TMPL同样位于 prompts.py要求模型Given a user question, and a list of tools, output a list of relevant sub-questions in json markdown并通过 Uber/Lyft 财务对比的示例引导输出{items: [...]}结构。值得注意的限制agenerate方法目前仅同步转发到generate源码注释明确说明guidance does not support async calls见 base.py因此异步场景下仍需走同步路径。交互式完整示例见 guidance_sub_question.ipynb。安装与依赖两个集成分别打包为独立发行包对应pyproject.toml如下llama-index-program-guidance提供GuidancePydanticProgram依赖guidance0.1.16,0.2与llama-index-core0.13.0,0.15要求 Python3.10,4.0llama-index-question-gen-guidance提供GuidanceQuestionGenerator额外依赖llama-index-program-guidance0.4.0,0.5。安装命令示例pip install llama-index-program-guidance llama-index-question-gen-guidance guidance两个包的[tool.llamahub]配置分别声明了import_path为llama_index.program.guidance与llama_index.question_gen.guidance与上文代码中的导入路径一一对应。API 参考文档也可在 program/guidance.md 与 question_gen/guidance.md 中查阅。小结通过本文你可以看到一条清晰的集成链路约束式结构化输出GuidancePydanticProgram把 Pydantic 模型转换为 Guidance 模板强制 LLM 输出合法 JSON从而彻底消除解析失败风险尤其适合弱模型场景模板兼容层convert_to_handlebars解决了 Python format string 与 handlebars 模板约定的差异让既有提示模板可以无缝迁移中间环节加固GuidanceQuestionGenerator复用同一套约束机制让SubQuestionQueryEngine的子问题生成结构稳定、可解析提升整条查询链路的鲁棒性。需要动手验证时推荐直接运行仓库中的两个 notebook——guidance_pydantic_program.ipynb 与 guidance_sub_question.ipynb并结合上述源码路径理解每一步的底层行为。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LlamaIndex × Guidance 集成实战用约束式结构化输出生成 Pydantic 对象并加固子问题查询引擎【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技术指南围绕 LlamaIndex 官方社区集成文档 guidance.md 展开系统讲解如何将微软开源的 Guidance 语言嵌入 LlamaIndex利用其强制约束能力让 LLM 直接产出符合 JSON Schema / Pydantic 模型的结构化对象并把这一能力注入SubQuestionQueryEngine的中间环节以提升子问题生成的鲁棒性。读完本文你将掌握GuidancePydanticProgram的完整用法、handlebars 模板转换原理以及GuidanceQuestionGenerator的接入方式。为什么需要 Guidance从建议结构到强制结构常规的 LLM 结构化输出做法是在提示词里请求模型输出一段 JSON再交给解析器处理。这种模式有两个隐患一是模型可能产出畸形 JSON例如缺少括号、字段错位二是解析失败时整个链路报错需要重试或容错逻辑。Guidance 提供了一条不同的路径它把生成generation、提示prompting和逻辑控制logical control交织进同一个连续流程与语言模型实际逐 token 处理文本的方式对齐。最关键的是它可以强制LLM 输出遵循指定 schema 的结构而不是仅仅建议——模型只需专注于内容本身语法层面的错误被彻底排除输出解析问题因此完全消失。这种能力对参数量较小、训练语料中源代码数据不足的弱模型尤其有价值它们难以稳定地生成格式良好、层级正确的结构化输出而 Guidance 的约束机制恰好弥补了这一短板。GuidancePydanticProgram一行代码生成 Pydantic 对象LlamaIndex 将 Guidance 的约束能力封装为GuidancePydanticProgram用于直接产出 Pydantic 对象。该实现位于 program/guidance/base.py继承自核心库中的BaseLLMFunctionProgram见 llm_prompt_program.py其单元测试 test_program_guidance.py 验证了类的继承关系。定义目标 schema假设我们要生成一张专辑包含歌名与时长schema 如下from pydantic import BaseModel from typing import List class Song(BaseModel): title: str length_seconds: int class Album(BaseModel): name: str artist: str songs: List[Song]注意 handlebars 模板约定Guidance 使用 handlebars 风格模板双花括号{{}}用于变量替换单花括号{}表示字面花括号——这与 Python format string 的约定恰好相反Python 中单花括号是变量占位符双花括号才是转义后的字面括号。好在 LlamaIndex 提供了convert_to_handlebars工具函数位于 guidance_utils.py可把 Python format string 风格的提示模板一键转换为 Guidance 的 handlebars 模板。该函数的转换逻辑是先将双花括号替换为临时占位符再把所有单花括号翻倍最后把占位符还原为单花括号从而完成两种约定之间的互转。创建并运行程序from llama_index.program.guidance import GuidancePydanticProgram from guidance.llms import OpenAI as GuidanceOpenAI program GuidancePydanticProgram( output_clsAlbum, prompt_template_strGenerate an example album, with an artist and a list of songs. Using the movie {{movie_name}} as inspiration, guidance_llmGuidanceOpenAI(text-davinci-003), verboseTrue, )然后像调用函数一样传入额外输入运行程序output program(movie_nameThe Shining)得到的就是一个结构完整的AlbumPydantic 对象Album( nameThe Shining, artistJack Torrance, songs[ Song(titleAll Work and No Play, length_seconds180), Song(titleThe Overlook Hotel, length_seconds240), Song(titleThe Shining, length_seconds210), ], )说明GuidancePydanticProgram内部通过user()/assistant()会话块包裹提示并追加gen(stop.)生成调用执行完成后会用parse_pydantic_from_guidance_program从返回文本中提取最后一个 markdown 格式的 JSON 代码块再经model_validate反序列化为目标 Pydantic 对象。由于当前 Guidance 版本尚不支持从Program.variables直接提取嵌套对象源码中对此采用了解析最终文本的临时方案注释中已明确标注详情见 guidance_utils.py。参数要点与 from_defaults 入口output_cls目标 Pydantic 模型类决定强制输出的 schemaprompt_template_strhandlebars 风格的提示模板其中的{{变量}}会在调用时以关键字参数传入guidance_llmGuidance 侧的 LLM 实例例如GuidanceOpenAI(text-davinci-003)若未提供源码中会默认回退到OpenAI(gpt-3.5-turbo)verbose是否打印原始输出便于调试。此外还提供了from_defaults类方法允许以promptPromptTemplate对象或prompt_template_str二选一的方式初始化两者都传或都不传会抛出ValueError。完整的可交互示例见 guidance_pydantic_program.ipynb。底层JSON Schema 到 Guidance 模板的自动转换在 guidance_utils.py 中json_schema_to_guidance_output_template负责把 Pydantic 模型的 JSON Schema 递归转换为 Guidance 约束模板object类型输出字面{...}结构逐字段展开array类型使用{{#geneach ...}}循环块配合stop]与可选的max_iterations对应 schema 的max_items控制列表长度元素间用{{#unless first}}, {{/unless}}插入逗号string类型使用{{gen key stop}}生成带结束符约束的字符串integer/number类型默认同样以stop约束可开启use_pattern_control用pattern[0-9\.]限定数字字符boolean类型使用{{#select key}}True{{or}}False{{/select}}强制二选一。该实现基于微软 guidance 仓库的 jsonformer 思路并扩展支持了嵌套 Pydantic 模型通过$ref解析到$defs。这也解释了为何弱模型也能稳定输出层级正确的 JSON——语法路径已被模板锁死。用 Guidance 加固 SubQuestionQueryEngine 的子问题生成LlamaIndex 提供了一系列高级查询引擎其中不少依赖中间步骤的结构化输出。若中间响应结构不稳定后续解析就会失败。Guidance 正好可以在此处发挥价值确保中间响应具备预期结构从而可被可靠地解析为结构化对象。集成文档给出了一个典型实践实现GuidanceQuestionGenerator并替换SubQuestionQueryEngine默认的问题生成器。其源码位于 question_gen/guidance/base.py对应单元测试见 test_question_gen_guidance_generator.py。from llama_index.question_gen.guidance import GuidanceQuestionGenerator from guidance.llms import OpenAI as GuidanceOpenAI # 定义基于 guidance 的问题生成器 question_gen GuidanceQuestionGenerator.from_defaults( guidance_llmGuidanceOpenAI(text-davinci-003), verboseFalse ) # 定义查询引擎工具 query_engine_tools ... # 构建子问题查询引擎 s_engine SubQuestionQueryEngine.from_defaults( question_genquestion_gen, # 使用上面定义的 guidance 版 question_gen query_engine_toolsquery_engine_tools, )内部实现剖析GuidanceQuestionGenerator继承自核心库的BaseQuestionGenerator其from_defaults内部以SubQuestionList为output_cls构建了一个GuidancePydanticProgram并使用默认子问题提示模板DEFAULT_GUIDANCE_SUB_QUESTION_PROMPT_TMPL convert_to_handlebars( DEFAULT_SUB_QUESTION_PROMPT_TMPL )核心的generate方法会把工具列表序列化为 JSON 文本build_tools_text见 prompts.py连同用户查询一起作为关键字参数传入程序最终返回List[SubQuestion]。默认提示模板DEFAULT_SUB_QUESTION_PROMPT_TMPL同样位于 prompts.py要求模型Given a user question, and a list of tools, output a list of relevant sub-questions in json markdown并通过 Uber/Lyft 财务对比的示例引导输出{items: [...]}结构。值得注意的限制agenerate方法目前仅同步转发到generate源码注释明确说明guidance does not support async calls见 base.py因此异步场景下仍需走同步路径。交互式完整示例见 guidance_sub_question.ipynb。安装与依赖两个集成分别打包为独立发行包对应pyproject.toml如下llama-index-program-guidance提供GuidancePydanticProgram依赖guidance0.1.16,0.2与llama-index-core0.13.0,0.15要求 Python3.10,4.0llama-index-question-gen-guidance提供GuidanceQuestionGenerator额外依赖llama-index-program-guidance0.4.0,0.5。安装命令示例pip install llama-index-program-guidance llama-index-question-gen-guidance guidance两个包的[tool.llamahub]配置分别声明了import_path为llama_index.program.guidance与llama_index.question_gen.guidance与上文代码中的导入路径一一对应。API 参考文档也可在 program/guidance.md 与 question_gen/guidance.md 中查阅。小结通过本文你可以看到一条清晰的集成链路约束式结构化输出GuidancePydanticProgram把 Pydantic 模型转换为 Guidance 模板强制 LLM 输出合法 JSON从而彻底消除解析失败风险尤其适合弱模型场景模板兼容层convert_to_handlebars解决了 Python format string 与 handlebars 模板约定的差异让既有提示模板可以无缝迁移中间环节加固GuidanceQuestionGenerator复用同一套约束机制让SubQuestionQueryEngine的子问题生成结构稳定、可解析提升整条查询链路的鲁棒性。需要动手验证时推荐直接运行仓库中的两个 notebook——guidance_pydantic_program.ipynb 与 guidance_sub_question.ipynb并结合上述源码路径理解每一步的底层行为。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
