LangExtract

目录

• 简介
• 为什么选择 LangExtract？
• 快速开始
• 安装
• 云模型的 API 密钥配置
• 添加自定义模型提供商
• 使用 OpenAI 模型
• 通过 Ollama 使用本地大语言模型（LLM）
• 更多示例
  • 罗密欧与朱丽叶全文提取
  • 药物信息提取
  • 放射科报告结构化：RadExtract
• 社区提供商
• 贡献指南
• 测试
• 免责声明

简介

LangExtract 是一个 Python 库，利用大型语言模型（LLM）根据用户定义的指令从非结构化文本文档中提取结构化信息。它处理临床笔记或报告等材料，识别并组织关键细节，同时确保提取的数据与源文本严格对应。

为什么选择 LangExtract？

1. 精准的源文本定位（Precise Source Grounding）： 将每次提取精确映射到源文本中的具体位置，支持可视化高亮显示，便于追溯和验证。
2. 可靠的结构化输出（Reliable Structured Outputs）： 基于您的少样本示例（few-shot examples）强制执行一致的输出模式，利用 Gemini 等支持模型的受控生成能力，确保结果稳健且结构化。
3. 长文档优化（Optimized for Long Documents）： 通过优化的文本分块策略、并行处理和多轮提取，克服大型文档中"大海捞针"的挑战，提高召回率。
4. 交互式可视化（Interactive Visualization）： 即时生成独立的交互式 HTML 文件，在原始上下文中可视化和审查数千个提取实体。
5. 灵活的 LLM 支持（Flexible LLM Support）： 支持您偏好的模型，从 Google Gemini 系列等云托管 LLM 到通过内置 Ollama 接口的本地开源模型。
6. 全领域适配（Adaptable to Any Domain）： 仅需少量示例即可定义任意领域的提取任务。LangExtract 无需模型微调即可适配您的需求。
7. 利用 LLM 世界知识（Leverages LLM World Knowledge）： 通过精确的提示词设计和少样本示例，影响提取任务如何利用 LLM 的知识。任何推断信息的准确性及其对任务规范的符合程度，取决于所选 LLM、任务复杂度、提示指令清晰度以及提示示例的性质。

快速开始

注意： 使用 Gemini 等云托管模型需要 API 密钥。请参阅 API 密钥配置 部分获取密钥申请和配置说明。

仅需几行代码即可提取结构化信息。

1. 定义提取任务

首先，创建一个清晰描述提取目标的提示词。然后提供高质量示例引导模型。

import langextract as lx
import textwrap

# 1. 定义提示词和提取规则
prompt = textwrap.dedent("""\
    按出现顺序提取角色、情绪和关系。
    使用原文文本进行提取，不得改写或重叠实体。
    为每个实体提供有意义的属性以补充上下文。""")

# 2. 提供高质量示例引导模型
examples = [
    lx.data.ExampleData(
        text="ROMEO. But soft! What light through yonder window breaks? It is the east, and Juliet is the sun.",
        extractions=[
            lx.data.Extraction(
                extraction_class="character",
                extraction_text="ROMEO",
                attributes={"emotional_state": "wonder"}
            ),
            lx.data.Extraction(
                extraction_class="emotion",
                extraction_text="But soft!",
                attributes={"feeling": "gentle awe"}
            ),
            lx.data.Extraction(
                extraction_class="relationship",
                extraction_text="Juliet is the sun",
                attributes={"type": "metaphor"}
            ),
        ]
    )
]

注意： 示例驱动模型行为。每个 extraction_text 应理想地直接取自示例的 text（不得改写），并按出现顺序列出。若示例不符合此模式，LangExtract 默认会触发 Prompt alignment 警告——为获得最佳结果，请解决这些警告。

源文本定位（Grounding）： LLM 有时可能从少样本示例而非输入文本中提取内容。LangExtract 会自动检测此情况：无法在源文本中定位的提取项将具有 char_interval = None。使用 [e for e in result.extractions if e.char_interval] 过滤，仅保留有定位的结果。

2. 执行提取

将输入文本和提示材料提供给 lx.extract 函数。

# 待处理的输入文本
input_text = "Lady Juliet gazed longingly at the stars, her heart aching for Romeo"

# 执行提取
result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash",
)

模型选择： gemini-2.5-flash 是推荐的默认选项，在速度、成本和质量间取得极佳平衡。对于需要深度推理的高复杂度任务，gemini-2.5-pro 可能提供更优结果。大规模或生产环境建议申请 Gemini Tier 2 配额以提升吞吐量并避免速率限制。详情参见 速率限制文档。

模型生命周期： Gemini 模型具有明确的生命周期和退役日期。用户应查阅 官方模型版本文档 了解最新稳定版和旧版信息。

3. 可视化结果

提取结果可保存为 .jsonl 文件（处理语言模型数据的常用格式）。LangExtract 可从此文件生成交互式 HTML 可视化界面，在上下文中审查实体。

# 将结果保存到 JSONL 文件
lx.io.save_annotated_documents([result], output_name="extraction_results.jsonl", output_dir=".")

# 从文件生成可视化
html_content = lx.visualize("extraction_results.jsonl")
with open("visualization.html", "w") as f:
    if hasattr(html_content, 'data'):
        f.write(html_content.data)  # For Jupyter/Colab
    else:
        f.write(html_content)

这将生成一个动画和交互式的 HTML 文件：

关于 LLM（大型语言模型）知识利用的说明： 本示例展示了紧密基于文本证据的提取——为朱丽叶小姐的情感状态提取 "longing"（渴望），并从 "gazed longingly at the stars" 中识别出 "yearning"（渴望）。该任务可以修改为生成更多依赖 LLM 世界知识的属性（例如，添加 "identity": "Capulet family daughter" 或 "literary_context": "tragic heroine"）。文本证据与知识推理之间的平衡由您的提示指令和示例属性控制。

扩展到更长文档

对于较大文本，您可以通过并行处理和增强敏感度直接从 URL 处理整个文档：

# 直接从 Project Gutenberg 处理《罗密欧与朱丽叶》
result = lx.extract(
    text_or_documents="https://www.gutenberg.org/files/1513/1513-0.txt",
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash",
    extraction_passes=3,    # 通过多次提取提高召回率
    max_workers=20,         # 并行处理以提升速度
    max_char_buffer=1000    # 更小的上下文以提高准确性
)

此方法可以从整部小说中提取数百个实体，同时保持高精度。交互式可视化无缝处理大型结果集，便于从输出的 JSONL 文件中探索数百个实体。查看完整的《罗密欧与朱丽叶》提取示例 → 以获取详细结果和性能洞察。

Vertex AI（谷歌云顶点 AI）批量处理

通过启用 Vertex AI 批量 API 降低大规模任务成本：language_model_params={"vertexai": True, "batch": {"enabled": True}}。

参见 this example 中的 Vertex AI 批量 API 使用示例。

安装

从 PyPI 安装

pip install langextract

推荐给大多数用户。对于隔离环境，建议使用虚拟环境：

python -m venv langextract_env
source langextract_env/bin/activate  # 在 Windows 上：langextract_env\Scripts\activate
pip install langextract

从源码安装

LangExtract 使用现代 Python 打包方式，通过 pyproject.toml 进行依赖管理：

使用 -e 安装会将包置于开发模式，允许您修改代码而无需重新安装。

git clone https://github.com/google/langextract.git
cd langextract

# 基础安装：
pip install -e .

# 开发环境（包含代码检查工具）：
pip install -e ".[dev]"

# 测试环境（包含 pytest）：
pip install -e ".[test]"

Docker

docker build -t langextract .
docker run --rm -e LANGEXTRACT_API_KEY="your-api-key" langextract python your_script.py

云模型的 API 密钥设置

当将 LangExtract 与云托管模型（如 Gemini 或 OpenAI）一起使用时，您需要设置 API 密钥。设备上模型不需要 API 密钥。对于使用本地 LLM（大型语言模型）的开发者，LangExtract 提供对 Ollama 的内置支持，并可通过更新推理端点扩展到其他第三方 API。

API 密钥来源

从以下位置获取 API 密钥：

• AI Studio 用于 Gemini 模型
• Vertex AI 用于企业级应用
• OpenAI Platform 用于 OpenAI 模型

在环境中设置 API 密钥

选项 1：环境变量

export LANGEXTRACT_API_KEY="your-api-key-here"

选项 2：.env 文件（推荐）

将您的 API 密钥添加到 .env 文件：

# 将 API 密钥添加到 .env 文件
cat >> .env << 'EOF'
LANGEXTRACT_API_KEY=your-api-key-here
EOF

# 保护您的 API 密钥安全
echo '.env' >> .gitignore

在您的 Python 代码中：

import langextract as lx

result = lx.extract(
    text_or_documents=input_text,
    prompt_description="Extract information...",
    examples=[...],
    model_id="gemini-2.5-flash"
)

选项 3：直接 API 密钥（不推荐用于生产环境）

您也可以在代码中直接提供 API 密钥，但不建议在生产环境中使用：

result = lx.extract(
    text_or_documents=input_text,
    prompt_description="Extract information...",
    examples=[...],
    model_id="gemini-2.5-flash",
    api_key="your-api-key-here"  # 仅用于测试/开发
)

选项 4：Vertex AI（服务账号）

使用 Vertex AI 通过服务账号进行身份验证：

result = lx.extract(
    text_or_documents=input_text,
    prompt_description="Extract information...",
    examples=[...],
    model_id="gemini-2.5-flash",
    language_model_params={
        "vertexai": True,
        "project": "your-project-id",
        "location": "global"  # 或区域端点
    }
)

添加自定义模型提供者

LangExtract 通过轻量级插件系统支持自定义 LLM 提供者。您可以在不更改核心代码的情况下添加对新模型的支持。

• 独立于核心库添加新模型支持
• 将您的提供者作为单独的 Python 包分发
• 保持自定义依赖项隔离
• 通过基于优先级的解析覆盖或扩展内置提供者

参见 Provider System Documentation 中的详细指南，了解如何：

• 使用 @registry.register(...) 注册提供者
• 发布用于发现的入口点
• 可选地通过 get_schema_class() 提供模式以实现结构化输出
• 通过 create_model(...) 与工厂集成

使用 OpenAI 模型

LangExtract 支持 OpenAI 模型（需要可选依赖：pip install langextract[openai]）：

import langextract as lx

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gpt-4o",  # 自动选择 OpenAI 提供者
    api_key=os.environ.get('OPENAI_API_KEY'),
    fence_output=True,
    use_schema_constraints=False
)

注意：OpenAI 模型需要 fence_output=True 和 use_schema_constraints=False，因为 LangExtract 尚未为 OpenAI 实现模式约束。

使用 Ollama 与本地大语言模型（LLM）

LangExtract 支持通过 Ollama（本地大语言模型运行框架）进行本地推理，无需 API 密钥即可运行模型：

import langextract as lx

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemma2:2b",  # 自动选择 Ollama 提供商
    model_url="http://localhost:11434",
    fence_output=False,
    use_schema_constraints=False
)

快速设置： 从 ollama.com 安装 Ollama，运行 ollama pull gemma2:2b，然后执行 ollama serve。

详细安装指南、Docker（容器化平台）配置及示例请参阅 examples/ollama/。

更多样例

LangExtract 实际应用的其他示例：

罗密欧与朱丽叶 全文提取

LangExtract 可直接从 URL 处理完整文档。本示例演示了从 Project Gutenberg 获取的 罗密欧与朱丽叶 全文（147,843 个字符）进行提取，展示了并行处理、顺序提取流程以及长文档处理的性能优化。

查看 罗密欧与朱丽叶 全文示例 →

药物信息提取

免责声明： 本演示仅用于说明 LangExtract 的基础能力，不代表已完成或获批的产品，不用于诊断或建议任何疾病/症状的治疗，不可作为医疗建议使用。

LangExtract 擅长从临床文本中提取结构化医疗信息。这些示例展示了基础实体识别（药物名称、剂量、给药途径）和关系提取（关联药物与其属性），体现 LangExtract 在医疗健康应用中的有效性。

查看药物提取示例 →

放射科报告结构化：RadExtract

探索 RadExtract，这是一个 HuggingFace Spaces 上的实时交互式演示，展示 LangExtract 如何自动结构化放射科报告。无需配置，直接在浏览器中体验。

查看 RadExtract 演示 →

社区提供商

通过自定义模型提供商扩展 LangExtract！查阅我们的 社区提供商插件 注册表，发现社区创建的提供商或添加您自己的插件。

创建提供商插件的详细说明请参见 自定义提供商插件示例。

贡献指南

欢迎贡献！参阅 CONTRIBUTING.md 了解开发、测试和提交拉取请求的流程。提交补丁前必须签署 贡献者许可协议。

测试

从源码本地运行测试：

# 克隆仓库
git clone https://github.com/google/langextract.git
cd langextract

# 安装测试依赖
pip install -e ".[test]"

# 运行所有测试
pytest tests

或使用 tox 本地复现完整 CI 矩阵（持续集成测试矩阵）：

tox  # 在 Python 3.10 和 3.11 上运行 pylint + pytest

Ollama 集成测试

若本地已安装 Ollama，可运行集成测试：

# 测试 Ollama 集成（需运行含 gemma2:2b 模型的 Ollama）
tox -e ollama-integration

该测试将自动检测 Ollama 可用性并执行真实推理测试。

开发指南

代码格式化

本项目使用自动化格式化工具保持代码风格一致：

# 自动格式化所有代码
./autoformat.sh

# 或分别运行格式化工具
isort langextract tests --profile google --line-length 80
pyink langextract tests --config pyproject.toml

预提交钩子

用于自动格式化检查：

pre-commit install  # 一次性设置
pre-commit run --all-files  # 手动执行

代码检查

提交 PR 前请运行代码检查：

pylint --rcfile=.pylintrc langextract tests

完整开发规范请参阅 CONTRIBUTING.md。

免责声明

本项目非 Google 官方支持产品。若在生产环境或出版物中使用 LangExtract，请适当引用并注明使用情况。使用受 Apache 2.0 License 约束。医疗相关应用还需遵守 Health AI Developer Foundations Terms of Use。

---

愉快提取！

LangExtract 快速上手指南

环境准备

• 系统要求：Python 3.8 或更高版本（推荐 3.10+）
• 前置依赖：
  • pip 包管理工具（随 Python 自动安装）
  • 建议使用虚拟环境隔离依赖（避免全局污染）
  • 使用云模型（如 Gemini）需提前准备 API Key（本地模型无需）

安装步骤

# 创建虚拟环境（推荐）
python -m venv langextract_env
source langextract_env/bin/activate  # Linux/Mac
# Windows 用户执行：langextract_env\Scripts\activate

# 使用国内镜像源加速安装（推荐清华源）
pip install langextract -i https://pypi.tuna.tsinghua.edu.cn/simple

# 验证安装
python -c "import langextract; print('安装成功')"

基本使用

以下是最简示例，从文本中提取角色、情绪和关系信息：

import langextract as lx
import textwrap

# 1. 定义提取任务（保持 prompt 清晰明确）
prompt = textwrap.dedent("""\
    Extract characters, emotions, and relationships in order of appearance.
    Use exact text for extractions. Do not paraphrase or overlap entities.""")

# 2. 提供示例（关键！决定模型行为）
examples = [
    lx.data.ExampleData(
        text="ROMEO. But soft! What light through yonder window breaks?",
        extractions=[
            lx.data.Extraction(
                extraction_class="character",
                extraction_text="ROMEO",
                attributes={"emotional_state": "wonder"}
            )
        ]
    )
]

# 3. 执行提取（使用默认 Gemini 模型）
input_text = "Lady Juliet gazed longingly at the stars"
result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-2.5-flash"  # 推荐默认模型
)

# 4. 查看结果（仅保留文本中的有效提取）
grounded_extractions = [e for e in result.extractions if e.char_interval]
print(grounded_extractions)

关键提示：

1. 示例必须严格使用原文片段（禁止改写），否则会触发 Prompt alignment 警告
2. 首次使用云模型需配置 API Key（设置指南）
3. 本地测试推荐 gemini-2.5-flash 模型，兼顾速度与准确性
4. 结果中的 char_interval 为 None 表示未在原文找到对应内容，需过滤