今天我们聊下Google 的新开源库 LangExtract。虽然他已经开源了一段时间。但这段时间我一直在实际项目里用它，踩了不少坑，也总结了一些经验。所以，这篇文章不打算讲太多理论，咱们直接上代码，聊实践。
如果你和我一样，曾被 RAG 系统里那些“相似但不相关”的检索结果折磨过，那 LangExtract 绝对值得你花十分钟看看。它只干一件事，但干得非常漂亮：给你的非结构化文本（产品文档、法律合同、用户评论等）精准地打上结构化标签，让RAG 搜索从“猜”变成“查”。
废话不多说，Show me the code。
一、基础篇：五分钟完成首次元数据提取
我们先来个最简单的例子，感受一下它的直接。
1. 环境准备
老规矩，虚拟环境，然后安装必要的库。LangExtract 自身不包含大模型，它作为一个调度和数据结构的库，需要一个后端模型来执行提取，这里我们使用 Google 的 Gemini。
pip install langextract google-generativeai
2. 配置 API 密钥
LangExtract 会默认读取名为LANGEXTRACT_API_KEY 的环境变量来驱动后端模型。
import os# 在实际项目中，请使用 .env 文件或系统环境变量等更安全的方式os.environ["LANGEXTRACT_API_KEY"]="YOUR_GOOGLE_API_KEY"
3. 首次提取代码
假设我们有一段应用服务的 API 简介，需要提取版本和速率。LangExtract 的设计基于“小样本提示”技术，这意味着我们必须提供至少一个完整的示例来“教会”模型，示例的质量直接决定了提取的质量。
import langextract as lximport textwrap
prompt = textwrap.dedent("""从技术文档中精准提取以下字段:1. service_name:从标题中提取出的主要服务或API名称(例如："认证API","存储服务")2. version_number:仅提取版本号数字(例如："2.0","1.0")，不要包含"v"或"版本"等文字。3. document_category:文档类型，提取原文中的"参考"、"指南"或"排错指南"。4. rate_limits:任何关于速率限制的信息，提取完整描述。""")
examples =[ lx.data.ExampleData( text="# 支付API v3.0 参考\n\n支付API用于处理所有交易请求。\n\n速率限制: 每分钟500次请求。", extractions=[ lx.data.Extraction(extraction_class="service_name", extraction_text="支付API"), lx.data.Extraction(extraction_class="version_number", extraction_text="3.0"), lx.data.Extraction(extraction_class="document_category", extraction_text="参考"), lx.data.Extraction(extraction_class="rate_limits", extraction_text="每分钟500次请求") ] ), lx.data.ExampleData( text="## 用户认证服务 - 排错指南\n\n本文档适用于 v1.5 版本。如果遇到认证失败，请检查您的API密钥。\n\n速率限制: 无。", extractions=[ lx.data.Extraction(extraction_class="service_name", extraction_text="用户认证服务"), lx.data.Extraction(extraction_class="version_number", extraction_text="1.5"), lx.data.Extraction(extraction_class="document_category", extraction_text="排错指南"), lx.data.Extraction(extraction_class="rate_limits", extraction_text="无") ] )]
input_text = textwrap.dedent(""" # 图像处理服务 - 开发者指南 欢迎使用我们的图像处理服务。当前稳定版本为2.1。 本指南将引导您完成所有设置步骤。 ### API调用频率 为了保证服务稳定，我们对所有用户设置了统一的调用频率上限：每小时1000次调用。""")
result_doc = lx.extract( text_or_documents=input_text, prompt_description=prompt, examples=examples, model_id="gemini-1.5-flash-latest",)
if result_doc.extractions: extracted_metadata ={ext.extraction_class: ext.extraction_text for ext in result_doc.extractions} print("提取出的结构化元数据:") for key, value in extracted_metadata.items(): print(f" - {key}: {value}")else: print("未能提取出任何信息。")
lx.io.save_annotated_documents([result_doc], output_name="extraction_results.jsonl", output_dir=".")html_content = lx.visualize("extraction_results.jsonl")with open("visualization.html","w", encoding="utf-8")as f: f.write(html_content.data)
运行结果：
提取出的结构化元数据:service_name:图像处理服务version_number:2.1document_category:指南rate_limits:每小时1000次调用
看，成了。这就是 LangExtract 的基本用法。但是，要真正发挥它的威力，我们需要一种更结构化的方式。
二、核心工作流 —— 同时提取文本及元数据
LangExtract 的精髓在于通过高质量的示例来指导模型。一个非常好的技巧是，在一次提取中，同时获得一个关键的文本片段（extraction_text）和一组描述该文本的属性字典（attributes）。
我们的目标是：从电影简介中，提取出主角实体（文本），并同步捕获这部电影的类型、角色类型和主题（元数据）。
1. 定义清晰的 Prompt
import textwrap
prompt = textwrap.dedent("""从电影简介中，找到核心角色，并提取出它的主要类型、主角类型和核心主题。""")
2. 提供一个标准答案的示例
这一步是关键中的关键。一个好的 Example 远胜千言万语的 Prompt。
examples =[ lx.data.ExampleData( text="一个孤独的太空陆战队员，在一颗遥远的星球上与外星生物作战。", extractions=[ lx.data.Extraction( extraction_class="protagonist",# 我们给这个提取对象一个类名 extraction_text="太空陆战队员",# 我们希望提取出的关键文本 attributes={# 我们希望关联到这段文本上的元数据 "genre":"科幻", "character_type":"军人", "theme":"战斗" } ) ] )]经验之谈：这种 extraction_text + attributes 的组合模式，对于构建复杂的 RAG 系统非常有用。比如，你可以提取出“公司名称”，并把它的“股票代码”、“成立年份”作为 attributes 附加。
3. 处理新文本
input ="一位年轻的巫师在霍格沃茨魔法学校发现了自己的魔法天赋，并与朋友们一起对抗黑魔王。"
result_doc = lx.extract( text_or_documents=input, prompt_description=prompt, examples=examples, model_id="gemini-1.5-flash-latest",)
if result_doc.extractions: extraction = result_doc.extractions[0] print(f"提取出的关键实体文本: {extraction.extraction_text}") print(f"关联的结构化元数据: {extraction.attributes}")else: print("未能提取出任何信息。")
运行结果：
提取出的关键实体文本:年轻的巫师关联的结构化元数据:{'genre':'奇幻','character_type':'魔法师','theme':'魔法与对抗'}模型不仅准确找到了主角“年轻的巫师”，还完美地生成了我们想要的结构化元数据。这就是 LangExtract 的核心工作流：定义任务（Prompt）-> 提供范本（Examples）-> 执行提取。
三、实战：构建 LangExtract + Milvus 混合检索管道
现在我们能稳定地从文本中提取丰富的元数据了。接下来，我们将它与 Milvus 结合，搭建一个完整的混合检索系统。选择 Milvus 的原因是我工作中深度使用，它对元数据过滤和混合检索的支持非常成熟。
1. 准备工作
2. 搭建数据注入流水线
流程很清晰：遍历文档 -> LangExtract 提取元数据 -> Google 模型生成向量 -> 存入 Milvus。
from pymilvus importMilvusClient,DataType,FieldSchema,CollectionSchemaimport google.generativeai as genai
genai.configure(api_key=os.environ["GEMINI_API_KEY"])
COLLECTION_NAME ="movie_db_prod"DB_FILE ="./milvus_movies.db"client =MilvusClient(uri=DB_FILE)
if client.has_collection(COLLECTION_NAME): client.drop_collection(COLLECTION_NAME)
fields =[ FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True), FieldSchema(name="text", dtype=DataType.VARCHAR, max_length=65535), FieldSchema(name="protagonist", dtype=DataType.VARCHAR, max_length=1024), FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=768)]schema =CollectionSchema(fields, enable_dynamic_field=True)client.create_collection(COLLECTION_NAME, schema=schema)
index_params = client.prepare_index_params()index_params.add_index(field_name="embedding", index_type="AUTOINDEX", metric_type="L2")client.create_index(COLLECTION_NAME, index_params)
input =["一个孤独的太空陆战队员，在一颗遥远的星球上与外星生物作战。","纽约警探约翰·麦克连在圣诞夜与恐怖分子在一栋洛杉矶摩天大楼里展开激战。","年轻巫师哈利·波特在霍格沃茨发现自己的魔法天赋，并对抗黑魔王。","一位天才发明家托尼·斯塔克打造了一套高科技战甲，成为钢铁侠。",]
all_data_entries =[]for plot in input: doc = lx.extract(plot, prompt_description=prompt, examples=examples, model_id="gemini-1.5-flash-latest") metadata ={} protagonist_text ="" if doc.extractions: metadata = doc.extractions[0].attributes protagonist_text = doc.extractions[0].extraction_text
embedding = genai.embed_content(model="models/text-embedding-004", content=plot, task_type="RETRIEVAL_DOCUMENT")['embedding']
data_entry ={ "text": plot, "protagonist": protagonist_text, "embedding": embedding, } data_entry.update(metadata) all_data_entries.append(data_entry)
client.insert(collection_name=COLLECTION_NAME, data=all_data_entries)print(f"成功注入 {len(all_data_entries)} 条数据到 Milvus!")
3. 混合检索与验证
数据入库，开始验证。
场景一：纯元数据过滤“帮我找到所有‘动作’类型的电影。”
results = client.query( collection_name=COLLECTION_NAME, filter='genre == "动作"',# 使用示例中存在的类型以确保有结果 output_fields=["text","genre","protagonist"])print("精确查询结果：\n", results)场景二：混合检索“找一些关于‘英雄成长’的电影，但必须是‘奇幻’类型。”
query_text ="英雄的成长与冒险"query_vector = genai.embed_content(model="models/text-embedding-004", content=query_text, task_type="RETRIEVAL_QUERY")['embedding']
search_results = client.search( collection_name=COLLECTION_NAME, data=[query_vector], limit=2, filter='genre == "奇幻"', output_fields=["text","genre","protagonist"])print("\n混合搜索结果：\n", search_results)
看到区别了吗？我们不再是盲目地在整个数据库里做向量ANN搜索，而是先用 LangExtract 提取出的精准标签（genre == "奇幻"）把搜索空间裁剪到一个极小的、高度相关的子集，然后再进行语义搜索。结果的准确性，完全不是一个量级。
四、一些经验之谈
1.别信你的第一版 Prompt 和 Examples。这个过程一定是迭代的。我的工作流是：跑一次 -> 结果不理想？-> 用 lx.visualize() 生成 HTML 报告看看模型到底把哪部分文本标错了 -> 修改 Examples 或 Prompt -> 再跑一次。visualize 是你最好的调试工具。2.Examples 的质量远比数量重要。一两个高质量、有代表性的示例，比十个随手写的低质量示例效果好得多。3.LangExtract 不是万能的。如果你的需求非常简单，比如只是想把一次 API 的返回强制规范成一个 JSON，那用 Instructor 这类轻量级库可能更直接。LangExtract 的主场是处理成批的、复杂的文档，为构建知识库提供稳定、高质量的元数据。4.LangExtract 只处理文本输入，需要预处理。LangExtract 的 API 接收的是字符串，它不负责文件解析。在处理 PDF、Word 或图片等格式时，必须建立一个预处理流水线：•对于 PDF/Word 文档：先用 PyMuPDF、python-docx 等库将文件内容解析为纯文本字符串，再交给 LangExtract。•对于图文混合内容：先提取文字，再用多模态模型（如 Gemini 1.5 Pro）将图片转换为文字描述，然后将两者合成为一份完整的纯文本文档，最后再由 LangExtract 处理。•记住这个流程：复杂文档 -> [解析器/多模态模型] -> 纯文本 -> [LangExtract]。五、总结
今天我们没有深入复杂的架构理论，而是纯粹地走了一遍如何用 LangExtract 和 Milvus 从零搭建一个高效的混合检索系统。
总结一下关键步骤：
1.用 lx.extract 加上清晰的 Prompt 和高质量的 Examples，从文本里提取元数据。2.将元数据和文本向量一同存入 Milvus。3.利用 Milvus 的 filter 功能实现“先过滤，再搜索”的精准查询。
粤ICP备14082021号
免费POC，
零成本试错
