超越嵌入检索用 Instructor 构建 RAG 查询理解系统Query Understanding【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor随着大语言模型LLM的普及检索增强生成RAG已成为最热门的话题之一。然而把用户查询直接 embedding 后丢进向量库搜索——这个看似标准的模式在真实业务中往往只是demo 级方案。本篇技术指南以 Instructor 为核心先剖析这种傻瓜式RAG 的四大缺陷再给出基于查询理解Query Understanding的升级路径用结构化输出把一条模糊的自然语言查询重写为带日期范围、域名白名单、关键词等多维度的检索请求并异步分发到多个搜索后端。读完你将掌握如何用 Instructor 在任意后端之上从零搭建一层LLM 查询理解层实现从语义相似检索到意图驱动的多路检索的实战升级。什么是傻瓜式RAG 模型所谓傻瓜式DumbRAG指的是这种最基础的搭建方式对用户查询做文本嵌入embedding然后在一个无差别的搜索接口里直接检索。整个系统被限制为单一的search(query: str) - List[str]方法。对于法国的首都是什么这类简单问题这种方式确实够用——因为巴黎是法国的首都这样的句子大概率会出现在维基百科嵌入结果的前几名里。但这只是最理想的情况。!!! note 什么是 RAG检索增强生成RAG是一种让 LLM 生成回答、但借助搜索后端来增强生成过程的技术。过去一年里使用文本嵌入配合向量数据库是最常见、被讨论最多的实现方式。为什么这是一个问题把傻瓜式RAG 拆开来看它在四个维度上存在系统性缺陷查询-文档不匹配Query-Document Mismatch这种模式假设查询嵌入和内容嵌入在向量空间中足够相似。但事实并非总是如此——它只支持与内容语义相似的查询这是一条巨大的限制。例如用户提问的措辞、抽象层级和文档正文差异较大时检索效果会急剧下降。单一化搜索后端Monolithic Search Backend它假设只有一个搜索后端但真实系统往往同时拥有多个后端——向量库、搜索客户端、SQL 数据库等各自有各自的 API。查询需要被路由到不同的后端而不是塞进同一个入口。文本搜索的表达力限制把复杂查询压缩成单个字符串{query: str}牺牲了关键词、过滤器等高级特性。例如我们上周修了哪些问题what problems did we fix last week这种问题纯文本搜索根本答不了——因为包含problem、last week的文档每周都会出现。规划能力受限Limited ability to plan它假设查询是搜索后端的唯一输入但你可能希望借助其他信息来改进搜索——比如用户的位置、当天的时间用更多上下文去重写查询。如果给语言模型更多上下文它甚至能规划出一组查询并逐一执行以返回最佳结果。用查询理解改进 RAG要解决上述问题最终要部署的是一个查询理解Query Understanding系统理解用户的查询意图将其重写以提升检索的精度precision与召回recall。从图上可以看出改进后的流程不再是一条直线查询进入 Query Engine 后被解析为多个结构化的 SearchRequest分别路由到不同后端最终汇总为面向 UI 或摘要的输出。用户不需要知道后端的具体细节系统自动完成查询重写 → 多路分发 → 结果整合。下面我们从理论转向实践看两个真实案例。什么是 InstructorInstructor 利用 Pydantic 简化程序员与语言模型之间的交互底层基于函数调用function callingAPI 实现结构化输出广泛采用Pydantic 是 Python 开发者中非常流行的工具简单直接Pydantic 允许直接用 Python 定义模型框架兼容许多 Python 框架本身已经在使用 Pydantic。在包入口中Instructor 以惰性导入lazy import方式暴露了from_provider、from_openai、from_anthropic、from_genai等工厂函数以及create系列调用所依赖的Instructor/AsyncInstructor客户端。其中from_provider的实现位于 instructor/v2/auto_client.py它要求模型字符串采用provider/model-name的格式例如openai/gpt-4.1-mini、anthropic/claude-3-sonnet内部根据 provider 前缀自动选择对应的 SDK 与默认模式OpenAI 默认Mode.TOOLSGemini 默认MD_JSON。它还支持以下常用参数参数说明async_clientTrue返回异步客户端AsyncInstructor配合await client.create(...)使用cache...传入缓存适配器如AutoCache透明地缓存响应mode...覆盖该 provider 的默认模式api_key...显式传入密钥否则从对应环境变量读取如OPENAI_API_KEYbase_url...、timeout...、max_retries...透传给底层 SDK 客户端创建出客户端后可用的核心调用方法定义在 instructor/v2/core/client.py 的Instructor/AsyncInstructor类中create返回单个结构化对象、create_partial流式产出部分对象、create_iterable流式产出对象列表、create_with_completion连同原始 completion 一起返回。后面两个案例正是围绕create展开的。案例一Metaphor Systems 式的查询理解以 Metaphor Systems 这类搜索产品为例它把自然语言查询转换成自身定制优化的搜索查询。在其 Web UI 中有一个auto-prompt自动提示选项底层正是用函数调用让语言模型进一步优化你的查询并把它变成一条完全规格化的 Metaphor 查询。如果掀开引擎盖你会发现这条查询其实是一个复杂的对象包含日期范围date range、要搜索的域名列表domains等。它实际比这更复杂但下面已经是一个很好的起点。我们可以用 Instructor 把这个结构化输出建模为 Pydantic 模型import datetime from typing import List from pydantic import BaseModel class DateRange(BaseModel): start: datetime.date end: datetime.date class MetaphorQuery(BaseModel): rewritten_query: str published_daterange: DateRange domains_allow_list: List[str] async def execute(): return await metaphor.search(...)注意我们建模了一条重写后的查询、一个发布时间范围、以及一个可搜索域名白名单。这个模式非常强大——它允许用户的查询为了更好的检索性能而被重构而用户完全不需要了解搜索后端的工作原理。然后用 Instructor 发起一次结构化调用import instructor # Enables response_model in the openai client client instructor.from_provider(openai/gpt-5-nano) query client.create( modelgpt-5.4-mini, response_modelMetaphorQuery, messages[ { role: system, content: Youre a query understanding system for the Metaphor Systems search engine. Here are some tips: ..., }, {role: user, content: What are some recent developments in AI?}, ], )示例输出{ rewritten_query: novel developments advancements ai artificial intelligence machine learning, published_daterange: { start: 2023-09-17, end: 2021-06-17 }, domains_allow_list: [arxiv.org] }说明上面代码中的模型名gpt-5-nano/gpt-5.4-mini为原文档演示所用实际运行时请替换为当前可用的模型名instructor/v2/auto_client.py 中from_provider支持openai/gpt-4.1-mini这类真实模型字符串。这绝不只是加了几个日期范围那么简单——这是与后端深度集成的、细致入微的定制检索。Metaphor Systems 还有一整套过滤器与选项可以构建更强大的搜索查询他们甚至可以用链式思考chain-of-thought提示来改进高级特性的使用方式。把这个思路落到 Pydantic 上就是在字段描述里引导模型逐步规划from datetime import date from pydantic import BaseModel, Field class DateRange(BaseModel): start: date end: date chain_of_thought: str Field( None, descriptionThink step by step to plan what is the best time range to search in, )案例二个人助手多后端异步分发查询理解这种多重分发模式multiple dispatch pattern的另一个绝佳例子是个人助手。你可能问一句我今天有什么安排——从一句模糊的查询出发你可能想要的是事件、邮件、提醒等。这些数据大概率存在于多个后端日历客户端、邮箱客户端甚至个人与工作账号而你想要的是一份统一的结果摘要。这里完全不能假设这些文档的文本都被嵌入进同一个搜索后端。用 Instructor 建模import asyncio import datetime import enum from typing import List from pydantic import BaseModel class ClientSource(enum.Enum): GMAIL gmail CALENDAR calendar class SearchClient(BaseModel): query: str keywords: List[str] email: str source: ClientSource start_date: datetime.date end_date: datetime.date async def execute(self) - str: if self.source ClientSource.GMAIL: ... elif self.source ClientSource.CALENDAR: ... class Retrieval(BaseModel): queries: List[SearchClient] async def execute(self) - str: return await asyncio.gather(*[query.execute() for query in self.queries])然后只需要一句简单的问题就能调用它系统会尝试异步分发到正确的后端import instructor # Enables response_model in the openai client client instructor.from_provider(openai/gpt-5-nano) retrieval client.create( modelgpt-5.4-mini, response_modelRetrieval, messages[ {role: system, content: You are Jasons personal assistant.}, {role: user, content: What do I have today?}, ], )示例输出{ queries: [ { query: null, keywords: null, email: jasonexample.com, source: gmail, start_date: 2023-09-17, end_date: null }, { query: null, keywords: [meeting, call, zoom], email: jasonexample.com, source: calendar, start_date: 2023-09-17, end_date: null } ] }注意我们得到的是一个路由到不同搜索后端邮件、日历的查询列表。我们可以把它们异步分发asyncio.gather尽可能提升性能。不仅分发到我们无法控制的多个后端你很可能还会以不同方式向用户渲染这些结果也许邮件适合用文本摘要而日历事件适合渲染成移动端可滚动的列表。!!! note 能使用框架 X 吗这个问题经常被问到——但它只是代码而已。在这些分发逻辑里你想做什么都可以用 input() 向用户追问更多信息、发起 POST 请求、调用 LangChain 的 agent 或 LlamaIndex 的查询引擎来获取更多信息。上限由你决定。这两个案例展示了搜索提供方和消费方都能用 Instructor 建模自己的系统。这是一个强大的模式它允许你构建一个任何人都能使用的系统并能在任意后端之前、从零搭建一层 LLM 层。模式总结综合两个案例可以提炼出这套查询理解 多路检索的核心套路用 Pydantic 建模查询请求不要只输出字符串而是输出带结构的对象——重写后的查询、关键词、日期范围、域名白名单、来源枚举等把执行逻辑挂到模型上在SearchClient、MetaphorQuery这类模型上定义async def execute()把查哪个后端、怎么查与结构化请求放在同一处一次生成、异步分发让 LLM 一次性产出一个List[SearchClient]检索计划再用asyncio.gather并行执行多个后端调用差异化渲染不同后端的返回结果按需采用不同的呈现方式文本摘要、列表、卡片等。从源码实现看这一模式的可行性由 instructor/v2/core/client.py 中的create系列方法保证create返回完整的 Pydantic 对象包括嵌套模型与枚举create_partial与create_iterable支持流式场景create_with_completion则能拿到原始 completion 用于调试或后处理。这意味着检索计划既可以一次成型也可以边生成边消费。结论这套方案无关花哨的嵌入技巧——它就是朴素的信息检索 查询理解。Instructor 的美妙之处在于它简化了对复杂事物的建模让你把语言模型的输出、提示词、以及发送给后端的 payload定义在同一个地方。下一步Instructor 不只是数据抽取工具它是一个强大的数据建模 LLM 集成框架。结构化输出只是起点——真正的金矿在于对工具与 API 的熟练运用。本仓库还提供了与本文主题直接相关的延伸阅读Validation Concepts —— 校验 RAG 输出含自动重试与语义校验LLM as Reranker —— 用 LLM 提升搜索相关性Citation Extraction —— 验证回答来源PDF Processing —— 文档处理含多模态【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
超越嵌入检索：用 Instructor 构建 RAG 查询理解系统（Query Understanding）
超越嵌入检索用 Instructor 构建 RAG 查询理解系统Query Understanding【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor随着大语言模型LLM的普及检索增强生成RAG已成为最热门的话题之一。然而把用户查询直接 embedding 后丢进向量库搜索——这个看似标准的模式在真实业务中往往只是demo 级方案。本篇技术指南以 Instructor 为核心先剖析这种傻瓜式RAG 的四大缺陷再给出基于查询理解Query Understanding的升级路径用结构化输出把一条模糊的自然语言查询重写为带日期范围、域名白名单、关键词等多维度的检索请求并异步分发到多个搜索后端。读完你将掌握如何用 Instructor 在任意后端之上从零搭建一层LLM 查询理解层实现从语义相似检索到意图驱动的多路检索的实战升级。什么是傻瓜式RAG 模型所谓傻瓜式DumbRAG指的是这种最基础的搭建方式对用户查询做文本嵌入embedding然后在一个无差别的搜索接口里直接检索。整个系统被限制为单一的search(query: str) - List[str]方法。对于法国的首都是什么这类简单问题这种方式确实够用——因为巴黎是法国的首都这样的句子大概率会出现在维基百科嵌入结果的前几名里。但这只是最理想的情况。!!! note 什么是 RAG检索增强生成RAG是一种让 LLM 生成回答、但借助搜索后端来增强生成过程的技术。过去一年里使用文本嵌入配合向量数据库是最常见、被讨论最多的实现方式。为什么这是一个问题把傻瓜式RAG 拆开来看它在四个维度上存在系统性缺陷查询-文档不匹配Query-Document Mismatch这种模式假设查询嵌入和内容嵌入在向量空间中足够相似。但事实并非总是如此——它只支持与内容语义相似的查询这是一条巨大的限制。例如用户提问的措辞、抽象层级和文档正文差异较大时检索效果会急剧下降。单一化搜索后端Monolithic Search Backend它假设只有一个搜索后端但真实系统往往同时拥有多个后端——向量库、搜索客户端、SQL 数据库等各自有各自的 API。查询需要被路由到不同的后端而不是塞进同一个入口。文本搜索的表达力限制把复杂查询压缩成单个字符串{query: str}牺牲了关键词、过滤器等高级特性。例如我们上周修了哪些问题what problems did we fix last week这种问题纯文本搜索根本答不了——因为包含problem、last week的文档每周都会出现。规划能力受限Limited ability to plan它假设查询是搜索后端的唯一输入但你可能希望借助其他信息来改进搜索——比如用户的位置、当天的时间用更多上下文去重写查询。如果给语言模型更多上下文它甚至能规划出一组查询并逐一执行以返回最佳结果。用查询理解改进 RAG要解决上述问题最终要部署的是一个查询理解Query Understanding系统理解用户的查询意图将其重写以提升检索的精度precision与召回recall。从图上可以看出改进后的流程不再是一条直线查询进入 Query Engine 后被解析为多个结构化的 SearchRequest分别路由到不同后端最终汇总为面向 UI 或摘要的输出。用户不需要知道后端的具体细节系统自动完成查询重写 → 多路分发 → 结果整合。下面我们从理论转向实践看两个真实案例。什么是 InstructorInstructor 利用 Pydantic 简化程序员与语言模型之间的交互底层基于函数调用function callingAPI 实现结构化输出广泛采用Pydantic 是 Python 开发者中非常流行的工具简单直接Pydantic 允许直接用 Python 定义模型框架兼容许多 Python 框架本身已经在使用 Pydantic。在包入口中Instructor 以惰性导入lazy import方式暴露了from_provider、from_openai、from_anthropic、from_genai等工厂函数以及create系列调用所依赖的Instructor/AsyncInstructor客户端。其中from_provider的实现位于 instructor/v2/auto_client.py它要求模型字符串采用provider/model-name的格式例如openai/gpt-4.1-mini、anthropic/claude-3-sonnet内部根据 provider 前缀自动选择对应的 SDK 与默认模式OpenAI 默认Mode.TOOLSGemini 默认MD_JSON。它还支持以下常用参数参数说明async_clientTrue返回异步客户端AsyncInstructor配合await client.create(...)使用cache...传入缓存适配器如AutoCache透明地缓存响应mode...覆盖该 provider 的默认模式api_key...显式传入密钥否则从对应环境变量读取如OPENAI_API_KEYbase_url...、timeout...、max_retries...透传给底层 SDK 客户端创建出客户端后可用的核心调用方法定义在 instructor/v2/core/client.py 的Instructor/AsyncInstructor类中create返回单个结构化对象、create_partial流式产出部分对象、create_iterable流式产出对象列表、create_with_completion连同原始 completion 一起返回。后面两个案例正是围绕create展开的。案例一Metaphor Systems 式的查询理解以 Metaphor Systems 这类搜索产品为例它把自然语言查询转换成自身定制优化的搜索查询。在其 Web UI 中有一个auto-prompt自动提示选项底层正是用函数调用让语言模型进一步优化你的查询并把它变成一条完全规格化的 Metaphor 查询。如果掀开引擎盖你会发现这条查询其实是一个复杂的对象包含日期范围date range、要搜索的域名列表domains等。它实际比这更复杂但下面已经是一个很好的起点。我们可以用 Instructor 把这个结构化输出建模为 Pydantic 模型import datetime from typing import List from pydantic import BaseModel class DateRange(BaseModel): start: datetime.date end: datetime.date class MetaphorQuery(BaseModel): rewritten_query: str published_daterange: DateRange domains_allow_list: List[str] async def execute(): return await metaphor.search(...)注意我们建模了一条重写后的查询、一个发布时间范围、以及一个可搜索域名白名单。这个模式非常强大——它允许用户的查询为了更好的检索性能而被重构而用户完全不需要了解搜索后端的工作原理。然后用 Instructor 发起一次结构化调用import instructor # Enables response_model in the openai client client instructor.from_provider(openai/gpt-5-nano) query client.create( modelgpt-5.4-mini, response_modelMetaphorQuery, messages[ { role: system, content: Youre a query understanding system for the Metaphor Systems search engine. Here are some tips: ..., }, {role: user, content: What are some recent developments in AI?}, ], )示例输出{ rewritten_query: novel developments advancements ai artificial intelligence machine learning, published_daterange: { start: 2023-09-17, end: 2021-06-17 }, domains_allow_list: [arxiv.org] }说明上面代码中的模型名gpt-5-nano/gpt-5.4-mini为原文档演示所用实际运行时请替换为当前可用的模型名instructor/v2/auto_client.py 中from_provider支持openai/gpt-4.1-mini这类真实模型字符串。这绝不只是加了几个日期范围那么简单——这是与后端深度集成的、细致入微的定制检索。Metaphor Systems 还有一整套过滤器与选项可以构建更强大的搜索查询他们甚至可以用链式思考chain-of-thought提示来改进高级特性的使用方式。把这个思路落到 Pydantic 上就是在字段描述里引导模型逐步规划from datetime import date from pydantic import BaseModel, Field class DateRange(BaseModel): start: date end: date chain_of_thought: str Field( None, descriptionThink step by step to plan what is the best time range to search in, )案例二个人助手多后端异步分发查询理解这种多重分发模式multiple dispatch pattern的另一个绝佳例子是个人助手。你可能问一句我今天有什么安排——从一句模糊的查询出发你可能想要的是事件、邮件、提醒等。这些数据大概率存在于多个后端日历客户端、邮箱客户端甚至个人与工作账号而你想要的是一份统一的结果摘要。这里完全不能假设这些文档的文本都被嵌入进同一个搜索后端。用 Instructor 建模import asyncio import datetime import enum from typing import List from pydantic import BaseModel class ClientSource(enum.Enum): GMAIL gmail CALENDAR calendar class SearchClient(BaseModel): query: str keywords: List[str] email: str source: ClientSource start_date: datetime.date end_date: datetime.date async def execute(self) - str: if self.source ClientSource.GMAIL: ... elif self.source ClientSource.CALENDAR: ... class Retrieval(BaseModel): queries: List[SearchClient] async def execute(self) - str: return await asyncio.gather(*[query.execute() for query in self.queries])然后只需要一句简单的问题就能调用它系统会尝试异步分发到正确的后端import instructor # Enables response_model in the openai client client instructor.from_provider(openai/gpt-5-nano) retrieval client.create( modelgpt-5.4-mini, response_modelRetrieval, messages[ {role: system, content: You are Jasons personal assistant.}, {role: user, content: What do I have today?}, ], )示例输出{ queries: [ { query: null, keywords: null, email: jasonexample.com, source: gmail, start_date: 2023-09-17, end_date: null }, { query: null, keywords: [meeting, call, zoom], email: jasonexample.com, source: calendar, start_date: 2023-09-17, end_date: null } ] }注意我们得到的是一个路由到不同搜索后端邮件、日历的查询列表。我们可以把它们异步分发asyncio.gather尽可能提升性能。不仅分发到我们无法控制的多个后端你很可能还会以不同方式向用户渲染这些结果也许邮件适合用文本摘要而日历事件适合渲染成移动端可滚动的列表。!!! note 能使用框架 X 吗这个问题经常被问到——但它只是代码而已。在这些分发逻辑里你想做什么都可以用 input() 向用户追问更多信息、发起 POST 请求、调用 LangChain 的 agent 或 LlamaIndex 的查询引擎来获取更多信息。上限由你决定。这两个案例展示了搜索提供方和消费方都能用 Instructor 建模自己的系统。这是一个强大的模式它允许你构建一个任何人都能使用的系统并能在任意后端之前、从零搭建一层 LLM 层。模式总结综合两个案例可以提炼出这套查询理解 多路检索的核心套路用 Pydantic 建模查询请求不要只输出字符串而是输出带结构的对象——重写后的查询、关键词、日期范围、域名白名单、来源枚举等把执行逻辑挂到模型上在SearchClient、MetaphorQuery这类模型上定义async def execute()把查哪个后端、怎么查与结构化请求放在同一处一次生成、异步分发让 LLM 一次性产出一个List[SearchClient]检索计划再用asyncio.gather并行执行多个后端调用差异化渲染不同后端的返回结果按需采用不同的呈现方式文本摘要、列表、卡片等。从源码实现看这一模式的可行性由 instructor/v2/core/client.py 中的create系列方法保证create返回完整的 Pydantic 对象包括嵌套模型与枚举create_partial与create_iterable支持流式场景create_with_completion则能拿到原始 completion 用于调试或后处理。这意味着检索计划既可以一次成型也可以边生成边消费。结论这套方案无关花哨的嵌入技巧——它就是朴素的信息检索 查询理解。Instructor 的美妙之处在于它简化了对复杂事物的建模让你把语言模型的输出、提示词、以及发送给后端的 payload定义在同一个地方。下一步Instructor 不只是数据抽取工具它是一个强大的数据建模 LLM 集成框架。结构化输出只是起点——真正的金矿在于对工具与 API 的熟练运用。本仓库还提供了与本文主题直接相关的延伸阅读Validation Concepts —— 校验 RAG 输出含自动重试与语义校验LLM as Reranker —— 用 LLM 提升搜索相关性Citation Extraction —— 验证回答来源PDF Processing —— 文档处理含多模态【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
