<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/google/langextract) · [上游 README](https://github.com/google/langextract/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<p align="center">
  <a href="https://github.com/google/langextract">
    <img src="https://raw.githubusercontent.com/google/langextract/main/docs/_static/logo.svg" alt="LangExtract Logo" width="128" />
  </a>
</p>

# LangExtract

[![PyPI version](https://img.shields.io/pypi/v/langextract.svg)](https://pypi.org/project/langextract/)
[![GitHub stars](https://img.shields.io/github/stars/google/langextract.svg?style=social&label=Star)](https://github.com/google/langextract)
![Tests](https://github.com/google/langextract/actions/workflows/ci.yaml/badge.svg)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17015089.svg)](https://doi.org/10.5281/zenodo.17015089)

## 目录

- [简介](#introduction)
- [为什么选择 LangExtract？](#why-langextract)
- [快速入门](#quick-start)
- [安装](#installation)
- [云端模型的 API 密钥配置](#api-key-setup-for-cloud-models)
- [添加自定义模型提供商](#adding-custom-model-providers)
- [使用 OpenAI 模型](#using-openai-models)
- [通过 Ollama 使用本地 LLM](#using-local-llms-with-ollama)
- [更多示例](#more-examples)
  - [*Romeo and Juliet* 全文抽取](#romeo-and-juliet-full-text-extraction)
  - [用药信息抽取](#medication-extraction)
  - [放射学报告结构化：RadExtract](#radiology-report-structuring-radextract)
- [社区提供商](#community-providers)
- [贡献](#contributing)
- [测试](#testing)
- [免责声明](#disclaimer)

## 简介

LangExtract 是一个 Python 库，可根据用户定义的指令，使用 LLM 从非结构化文本文档中抽取结构化信息。它可处理临床笔记或报告等材料，识别并整理关键细节，同时确保抽取的数据与源文本相对应。

## 为什么选择 LangExtract？

1.  **精确的源文本锚定（Source Grounding）：** 将每次抽取映射到源文本中的确切位置，支持可视化高亮，便于追溯与核验。
2.  **可靠的结构化输出：** 基于你的少样本（few-shot）示例强制执行一致的输出模式（schema），并在 Gemini 等支持的模型中利用受控生成（controlled generation），以保证稳健、结构化的结果。
3.  **针对长文档优化：** 通过优化的文本分块、并行处理与多轮遍历策略，克服大型文档抽取中的“大海捞针”难题，提高召回率。
4.  **交互式可视化：** 即时生成自包含的交互式 HTML 文件，在原始上下文中可视化并审阅数千条抽取实体。
5.  **灵活的 LLM 支持：** 支持你所偏好的模型，从 Google Gemini 系列等云端 LLM，到通过内置 Ollama 接口使用的本地开源模型。
6.  **适配任意领域：** 仅用少量示例即可为任意领域定义抽取任务。LangExtract 可按需适配，无需对模型进行微调。
7.  **利用 LLM 世界知识：** 通过精确的提示词措辞与少样本示例，影响抽取任务对 LLM 知识的运用方式。任何推断信息的准确性及其对任务规范的遵循程度，取决于所选 LLM、任务复杂度、提示指令的清晰度以及示例的性质。

## 快速入门

> **注意：** 使用 Gemini 等云端托管模型需要 API 密钥。请参阅 [API 密钥配置](#api-key-setup-for-cloud-models) 一节，了解如何获取并配置密钥。

只需几行代码即可抽取结构化信息。

### 1. 定义抽取任务

首先，编写一段清晰描述你想抽取内容的提示词。然后，提供一个高质量示例以引导模型。

```python
import langextract as lx
import textwrap

# 1. Define the prompt and extraction rules
prompt = textwrap.dedent("""\
    Extract characters, emotions, and relationships in order of appearance.
    Use exact text for extractions. Do not paraphrase or overlap entities.
    Provide meaningful attributes for each entity to add context.""")

# 2. Provide a high-quality example to guide the model
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` 函数。

```python
# The input text to be processed
input_text = "Lady Juliet gazed longingly at the stars, her heart aching for Romeo"

# Run the extraction
result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemini-3.5-flash",
)
```

对于超出示例范围的高级约束（例如抽取属性上的枚举值），Gemini 与 OpenAI 支持带或不带少样本示例的 `output_schema`。请参阅
[自定义输出模式](docs/examples/output_schema.md)。

> **模型选择**：`gemini-3.5-flash` 是推荐的默认选项，在 LangExtract 的模式约束工作流中可提供较强的抽取质量。对于高吞吐量或成本敏感的工作负载，可考虑当前稳定的 Flash-Lite 模型 `gemini-3.1-flash-lite`；对于需要更深推理的高度复杂任务，可评估官方模型文档中的当前 Gemini Pro 模型。对于大规模或生产环境使用，建议使用付费 Gemini 套餐以提高吞吐量并避免速率限制。详情请参阅[速率限制文档](https://ai.google.dev/gemini-api/docs/rate-limits#usage-tiers)。
>
> **模型生命周期**：请注意，Gemini 模型具有定义了退役日期的生命周期。用户应查阅[官方模型版本文档](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions)，以了解最新的稳定版与旧版信息。

### 3. 可视化结果

抽取结果可保存为 `.jsonl` 文件——这是处理语言模型数据的常用格式。LangExtract 随后可基于该文件生成交互式 HTML 可视化，以便在上下文中审阅实体。

```python
# Save the results to a JSONL file
lx.io.save_annotated_documents([result], output_name="extraction_results.jsonl", output_dir=".")

# Generate the visualization from the file
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 文件：

![Romeo and Juliet Basic Visualization ](https://raw.githubusercontent.com/google/langextract/main/docs/_static/romeo_juliet_basic.gif)

> **关于 LLM 知识运用的说明：** 本示例演示的抽取结果紧贴文本证据——为 Lady Juliet 的情绪状态抽取“longing”，并从“gazed longingly at the stars”中识别“yearning”。该任务可修改为生成更多依赖 LLM 世界知识的属性（例如添加 `"identity": "Capulet family daughter"` 或 `"literary_context": "tragic heroine"`）。文本证据与知识推断之间的平衡，由你的提示指令与示例属性控制。

### 扩展到更长文档

对于较长的文本，你可以通过并行处理和增强的敏感度，直接从 URL 处理整篇文档：

```python
# Process Romeo & Juliet directly from 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-3.5-flash",
    extraction_passes=3,    # Improves recall through multiple passes
    max_workers=20,         # Parallel processing for speed
    max_char_buffer=1000    # Smaller contexts for better accuracy
)
```

这种方法可以从完整小说中抽取数百个实体，同时保持高准确度。交互式可视化可无缝处理大型结果集，便于从输出的 JSONL 文件中探索数百个实体。**[查看完整的 *Romeo and Juliet* 抽取示例 →](https://github.com/google/langextract/blob/main/docs/examples/longer_text_example.md)** for detailed results and performance insights.

### Vertex AI 批处理

通过启用 Vertex AI Batch API，并配合包含 `vertexai=True`、`project`、`location` 以及 `batch` 配置的 `language_model_params`，可在大规模任务中节省成本。

在 [此示例](docs/examples/batch_api_example.md) 中查看 Vertex AI Batch API 的用法示例。

## 安装

### 从 PyPI 安装

```bash
pip install langextract
```

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

```bash
python -m venv langextract_env
source langextract_env/bin/activate  # On Windows: langextract_env\Scripts\activate
pip install langextract
```

### 从源码安装

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

*使用 `-e` 安装会将软件包置于开发模式，允许你在不重新安装的情况下修改代码。*


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

# For basic installation:
pip install -e .

# For development (includes linting tools):
pip install -e ".[dev]"

# For testing (includes pytest):
pip install -e ".[test]"
```

### Docker

```bash
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](https://aistudio.google.com/app/apikey) for Gemini models
*   [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/sdks/overview) for enterprise use
*   [OpenAI Platform](https://platform.openai.com/api-keys) for OpenAI models

### 在环境中配置 API 密钥

**选项 1：环境变量**

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

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

将 API 密钥添加到 `.env` 文件中：

```bash
# Add API key to .env file
cat >> .env << 'EOF'
LANGEXTRACT_API_KEY=your-api-key-here
EOF

# Keep your API key secure
echo '.env' >> .gitignore
```

在 Python 代码中：
```python
import langextract as lx

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

**选项 3：直接传入 API 密钥（不建议用于生产环境）**

你也可以在代码中直接提供 API 密钥，但不建议在生产环境中这样做：

```python
result = lx.extract(
    text_or_documents=input_text,
    prompt_description="Extract information...",
    examples=[...],
    model_id="gemini-3.5-flash",
    api_key="your-api-key-here"  # Only use this for testing/development
)
```

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

使用 [Vertex AI](https://cloud.google.com/vertex-ai/docs/start/introduction-unified-platform) for authentication with service accounts:

```python
result = lx.extract(
    text_or_documents=input_text,
    prompt_description="Extract information...",
    examples=[...],
    model_id="gemini-3.5-flash",
    language_model_params={
        "vertexai": True,
        "project": "your-project-id",
        "location": "global"  # or regional endpoint
    }
)
```

## 添加自定义模型提供方

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

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

请参阅 [Provider System Documentation（提供方系统文档）](langextract/providers/README.md) 中的详细指南，了解如何：

- 使用 `@router.register(...)` 从 `langextract.providers` 注册提供方
- 发布用于发现的入口点（entry point）
- 可选地使用 `get_schema_class()` 提供结构化输出的 schema
- 通过 `create_model(...)` 与工厂（factory）集成

## 使用 OpenAI 模型

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

```python
import langextract as lx

# OPENAI_API_KEY in the environment is picked up automatically; pass
# api_key=... explicitly only if you need to override it.
result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gpt-4o",  # Automatically selects OpenAI provider
)
```

OpenAI 提供方使用结构化输出（structured outputs）或 JSON 模式，并自动确定
围栏（fence）行为——请将 `fence_output` 和 `use_schema_constraints` 留空。
对于支持结构化输出的 OpenAI 模型，还支持 `output_schema`；请提供 LangExtract 输出封装（output-envelope）JSON schema，最好配合
`lx.schema` 辅助工具使用。

对于大规模、对延迟不敏感的 OpenAI 工作负载，可通过 `language_model_params` 启用 OpenAI Batch API。
批处理模式为可选启用，当提示（prompt）数量低于配置阈值时会回退到实时调用。

```python
result = lx.extract(
    text_or_documents=documents,
    prompt_description=prompt,
    examples=examples,
    model_id="gpt-4o-mini",
    language_model_params={
        "batch": {
            "enabled": True,
            "threshold": 50,
            "poll_interval": 10,
        }
    },
)
```

对于 OpenAI 兼容端点或非 GPT 模型 ID（会跳过自动路由），请使用 `ModelConfig` 并显式指定提供方：

```python
from langextract.factory import ModelConfig

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    config=ModelConfig(
        model_id="my-openai-compatible-model",
        provider="openai",
        provider_kwargs={"api_key": "sk-...", "base_url": "https://..."},
    ),
)
```

## 使用 Ollama 运行本地 LLM
LangExtract 支持通过 Ollama 进行本地推理，无需 API 密钥即可运行模型：

```python
import langextract as lx

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt,
    examples=examples,
    model_id="gemma2:2b",  # Automatically selects Ollama provider
    model_url="http://localhost:11434",
)
```

Ollama 提供方为 JSON 模式公开了 `FormatModeSchema`。请将 `fence_output`
和 `use_schema_constraints` 留空，以便工厂根据提供方的
schema 自动配置。Ollama 目前不支持 `output_schema`。

**快速设置：** 从 [ollama.com](https://ollama.com/), 安装 Ollama，运行 `ollama pull gemma2:2b`，然后执行 `ollama serve`。

有关详细安装、Docker 配置和示例，请参阅 [`examples/ollama/`](examples/ollama/)。

## 更多示例

LangExtract 的更多实际应用示例：

### *Romeo and Juliet* 全文抽取

LangExtract 可直接从 URL 处理完整文档。本示例演示从 Project Gutenberg 上的 *Romeo and Juliet* 全文（147,843 个字符）中进行抽取，展示并行处理、顺序抽取轮次以及长文档处理的性能优化。

**[查看 *Romeo and Juliet* 全文示例 →](https://github.com/google/langextract/blob/main/docs/examples/longer_text_example.md)**

### 药物提取

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

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

**[查看药物提取示例 →](https://github.com/google/langextract/blob/main/docs/examples/medication_examples.md)**

### 放射学报告结构化：RadExtract

探索 RadExtract——HuggingFace Spaces 上的实时交互式演示，展示 LangExtract 如何自动结构化放射学报告。无需任何配置，直接在浏览器中试用。

**[查看 RadExtract 演示 →](https://huggingface.co/spaces/google/radextract)**

## 社区提供商（Community Providers）

使用自定义模型提供商扩展 LangExtract！查看我们的[社区提供商插件](COMMUNITY_PROVIDERS.md)注册表，发现社区创建的提供商或添加你自己的。

有关创建提供商插件的详细说明，请参阅[自定义提供商插件示例](examples/custom_provider_plugin/)。

## 贡献

欢迎贡献！请参阅 [CONTRIBUTING.md](https://github.com/google/langextract/blob/main/CONTRIBUTING.md) 了解如何开始开发、测试和提交拉取请求。提交补丁前，你必须签署[贡献者许可协议](https://cla.developers.google.com/about)
（Contributor License Agreement）。

## 测试

从源码在本地运行测试：

```bash
# Clone the repository
git clone https://github.com/google/langextract.git
cd langextract

# Install with test dependencies
pip install -e ".[test]"

# Run all tests
pytest tests
```

或使用 tox 在本地复现完整 CI 矩阵：

```bash
tox  # runs pylint + pytest on Python 3.10 and 3.11
```

### Ollama 集成测试

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

```bash
# Test Ollama integration (requires Ollama running with gemma2:2b model)
tox -e ollama-integration
```

该测试会自动检测 Ollama 是否可用，并运行真实推理测试。

## 开发

### 代码格式化

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

```bash
# Auto-format all code
./autoformat.sh

# Or run formatters separately
isort langextract tests --profile google --line-length 80
pyink langextract tests --config pyproject.toml
```

### Pre-commit 钩子

自动格式化检查：

```bash
pre-commit install  # One-time setup
pre-commit run --all-files  # Manual run
```

### 代码检查（Linting）

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

```bash
pylint --rcfile=.pylintrc langextract tests
```

完整开发指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 免责声明

这不是 Google 官方支持的产品。若你在生产环境或出版物中使用 LangExtract，请按规定引用并注明使用情况。使用须遵守 [Apache 2.0 许可证](https://github.com/google/langextract/blob/main/LICENSE).
。对于医疗相关应用，LangExtract 的使用还须遵守[Health AI Developer Foundations 使用条款](https://developers.google.com/health-ai-developer-foundations/terms).

---

**祝你提取愉快！**