关于 langchain_community.document_transformers 模块下的类和函数

langchain_community.document_transformers 模块是 LangChain 社区库的一部分，提供了多种文档转换器，用于处理、清洗、增强或转换文档内容。这些转换器主要用于文档预处理，适用于检索增强生成（RAG）、数据提取、文本清洗等场景。以下是对用户指定的每个类和函数的详细介绍，包括定义、功能、属性、方法、使用方式、应用场景、优化建议和注意事项。

---

1. BeautifulSoupTransformer

定义

BeautifulSoupTransformer 是一个文档转换器，使用 BeautifulSoup 库从 HTML 文档中提取或移除特定标签内容。它允许用户清洗 HTML 文档，保留或删除指定的 HTML 标签，生成纯文本或其他结构化输出。

核心功能

• 提取指定标签：从 HTML 文档中提取用户指定的标签内容（如 <p>、<h1>）。
• 移除指定标签：删除不需要的标签（如 <script>、<style>），清洗文档。
• 支持自定义解析：基于 BeautifulSoup 的强大解析能力，支持复杂 HTML 结构。
• 批量处理：处理多个 Document 对象，返回转换后的文档列表。

核心属性与方法

• 属性：
  • tags_to_extract：List[str]，要提取的 HTML 标签列表（如 ["p", "h1"]）。
  • tags_to_remove：List[str]，要移除的 HTML 标签列表（如 ["script", "style"]）。
  • parser：str，BeautifulSoup 使用的解析器（如 "html.parser" 或 "lxml"）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：将输入文档列表转换为清洗后的文档列表。
  • atransform_documents(documents: List[Document], **kwargs) -> AsyncIterator[Document]：异步版本的转换方法。

使用方式与代码示例

from langchain_community.document_transformers import BeautifulSoupTransformer
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="<html><p>这是正文</p><script>恶意脚本</script></html>")
]

# 初始化转换器
transformer = BeautifulSoupTransformer(tags_to_extract=["p"], tags_to_remove=["script"])

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].page_content)

输出：

这是正文

说明：

• 提取 <p> 标签的内容，移除 <script> 标签，生成纯文本。

应用场景

• 网页清洗：从爬取的网页中提取正文，移除广告或脚本。
• 数据预处理：为 RAG 系统清洗 HTML 文档，保留有用内容。
• 文本提取：从复杂 HTML 结构中提取特定部分（如文章标题、正文）。

优化建议

• 选择高效解析器：使用 "lxml" 解析器以提高性能（需安装 lxml）。
• 精简标签列表：仅指定必要的 tags_to_extract 和 tags_to_remove，减少处理开销。
• 批量处理：一次性处理大量文档，优化性能。

注意事项

• 依赖 BeautifulSoup：需安装 beautifulsoup4 和可选的 lxml。
• 标签选择：确保指定的标签存在，否则可能返回空内容。
• 编码问题：处理非 UTF-8 编码的 HTML 时，需确保正确解码。

---

2. DoctranPropertyExtractor

定义

DoctranPropertyExtractor 使用 Doctran 库通过自然语言处理（NLP）从文档中提取特定属性（如人名、日期、金额）。它利用语言模型分析文本，生成结构化输出。

核心功能

• 属性提取：从非结构化文本中提取用户定义的属性。
• 结构化输出：将提取结果存储在文档的 metadata 字段中。
• 支持自定义属性：用户可以指定要提取的属性类型和描述。
• 批量处理：处理多个文档，返回更新后的文档列表。

核心属性与方法

• 属性：
  • properties：List[Dict]，定义要提取的属性（如 [{"name": "person", "type": "string", "description": "人名"}]）。
  • model：使用的语言模型（如 OpenAI 的 GPT 模型）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：提取属性并更新文档元数据。
  • atransform_documents(documents: List[Document], **kwargs) -> AsyncIterator[Document]：异步版本。

使用方式与代码示例

from langchain_community.document_transformers import DoctranPropertyExtractor
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="Alice 在 2023-05-01 支付了 $100。")
]

# 定义要提取的属性
properties = [
    {"name": "person", "type": "string", "description": "人名"},
    {"name": "date", "type": "string", "description": "日期"},
    {"name": "amount", "type": "string", "description": "金额"}
]

# 初始化转换器
transformer = DoctranPropertyExtractor(properties=properties, openai_api_key="your-api-key")

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].metadata)

输出：

{'person': 'Alice', 'date': '2023-05-01', 'amount': '$100'}

说明：

• 从文本中提取人名、日期和金额，存储在 metadata 中。

应用场景

• 信息提取：从合同、报告或新闻中提取关键信息。
• 元数据增强：为 RAG 系统添加结构化元数据。
• 自动化处理：处理大量文档，提取特定字段。

优化建议

• 精确属性定义：提供清晰的属性描述，提高提取准确性。
• 缓存结果：对于重复文档，使用缓存减少 API 调用。
• 异步处理：使用 atransform_documents 处理大批量文档。

注意事项

• 依赖 Doctran：需安装 doctran 和配置 API 密钥。
• 模型成本：使用外部模型（如 OpenAI）可能产生费用。
• 提取准确性：复杂文本可能导致提取错误，需验证结果。

---

3. DoctranQATransformer

定义

DoctranQATransformer 使用 Doctran 库将文档转换为问答对格式。它通过语言模型分析文档内容，生成问题和答案对，适合构建问答数据集或增强 RAG 系统。

核心功能

• 生成问答对：从文档中自动生成问题和答案。
• 结构化输出：将问答对存储在文档的 metadata 或新文档中。
• 支持自定义配置：用户可以指定生成的问题数量或类型。
• 批量处理：处理多个文档，返回转换后的文档列表。

核心属性与方法

• 属性：
  • num_questions：int，为每个文档生成的问题数量。
  • model：使用的语言模型（如 OpenAI 的 GPT 模型）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：生成问答对并更新文档。
  • atransform_documents(documents: List[Document], **kwargs) -> AsyncIterator[Document]：异步版本。

使用方式与代码示例

from langchain_community.document_transformers import DoctranQATransformer
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="量子计算利用量子比特进行并行计算。")
]

# 初始化转换器
transformer = DoctranQATransformer(num_questions=2, openai_api_key="your-api-key")

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].metadata)

输出：

{
    'qa_pairs': [
        {'question': '量子计算使用什么进行计算？', 'answer': '量子比特'},
        {'question': '量子计算的特点是什么？', 'answer': '并行计算'}
    ]
}

说明：

• 为文档生成两个问答对，存储在 metadata 中。

应用场景

• 问答数据集：为训练或测试生成问答数据集。
• RAG 增强：为 RAG 系统提供问答上下文。
• 教育工具：从教材中生成复习问题。

优化建议

• 控制问题数量：设置合理的 num_questions，避免生成过多问题。
• 验证问答质量：检查生成的问题和答案是否准确。
• 异步处理：使用 atransform_documents 提高效率。

注意事项

• 依赖 Doctran：需安装 doctran 和配置 API 密钥。
• 模型依赖：生成质量依赖于使用的语言模型。
• 成本考虑：大量文档可能导致高 API 调用费用。

---

4. DoctranTextTranslator

定义

DoctranTextTranslator 使用 Doctran 库将文档内容翻译为指定语言。它利用语言模型进行高质量翻译，适合多语言应用。

核心功能

• 文本翻译：将文档内容从源语言翻译到目标语言。
• 语言检测：自动检测源语言（可选）。
• 批量处理：处理多个文档，返回翻译后的文档列表。
• 元数据保留：保持文档的原始元数据。

核心属性与方法

• 属性：
  • target_language：str，目标语言（如 "es" 表示西班牙语）。
  • model：使用的语言模型（如 OpenAI 的 GPT 模型）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：翻译文档内容。
  • atransform_documents(documents: List[Document], **kwargs) -> AsyncIterator[Document]：异步版本。

使用方式与代码示例

from langchain_community.document_transformers import DoctranTextTranslator
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="Quantum computing is exciting.")
]

# 初始化转换器
transformer = DoctranTextTranslator(target_language="es", openai_api_key="your-api-key")

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].page_content)

输出：

La computación cuántica es emocionante.

说明：

• 将英文内容翻译为西班牙语。

应用场景

• 多语言 RAG：为多语言用户提供翻译后的文档。
• 国际化应用：翻译文档内容以支持全球用户。
• 数据增强：生成多语言版本的训练数据。

优化建议

• 批量翻译：一次性处理多个文档，减少 API 调用。
• 缓存翻译：对于重复内容，使用缓存避免重复翻译。
• 目标语言验证：确保 target_language 使用标准语言代码（如 ISO 639-1）。

注意事项

• 依赖 Doctran：需安装 doctran 和配置 API 密钥。
• 翻译质量：复杂句子可能导致翻译偏差，需人工验证。
• 成本管理：翻译大量文档可能产生高费用。

---

5. EmbeddingsClusteringFilter

定义

EmbeddingsClusteringFilter 使用嵌入向量和聚类算法（如 K-Means）过滤文档，移除语义上相似的冗余文档。它基于文档的嵌入表示进行聚类，仅保留每个簇的代表性文档。

核心功能

• 语义聚类：根据嵌入向量将文档分组，识别相似内容。
• 冗余过滤：从每个簇中选择一个代表性文档，移除其他冗余文档。
• 支持自定义嵌入：使用用户提供的嵌入模型（如 OpenAIEmbeddings）。
• 批量处理：处理多个文档，返回过滤后的文档列表。

核心属性与方法

• 属性：
  • embeddings：嵌入模型实例（如 OpenAIEmbeddings）。
  • n_clusters：int，聚类数量（默认自动确定）。
  • distance_metric：str，距离度量（如 "cosine"）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：聚类并过滤文档。
  • fit(documents: List[Document]) -> None：训练聚类模型（可选）。

使用方式与代码示例

from langchain_community.document_transformers import EmbeddingsClusteringFilter
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="量子计算很酷。"),
    Document(page_content="量子计算非常有趣。"),
    Document(page_content="经典计算很稳定。")
]

# 初始化嵌入模型和转换器
embeddings = OpenAIEmbeddings(api_key="your-api-key")
transformer = EmbeddingsClusteringFilter(embeddings=embeddings, n_clusters=2)

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print([doc.page_content for doc in transformed_docs])

输出：

['量子计算很酷。', '经典计算很稳定。']

说明：

• 将语义相似的量子计算文档聚为一类，仅保留一个代表性文档。

应用场景

• 去重处理：从大量文档中移除语义冗余内容。
• RAG 优化：减少检索结果中的重复文档，提高效率。
• 数据清洗：为训练数据去除相似样本。

优化建议

• 选择合适的 n_clusters：根据文档数量和多样性调整聚类数量。
• 高效嵌入模型：使用快速嵌入模型（如 SentenceTransformers）降低计算成本。
• 预计算嵌入：缓存文档嵌入，加速后续处理。

注意事项

• 依赖嵌入模型：需安装嵌入模型（如 langchain_openai）。
• 聚类质量：聚类效果依赖嵌入质量和 n_clusters 设置。
• 计算开销：处理大量文档可能需要较高计算资源。

---

6. EmbeddingsRedundantFilter

定义

EmbeddingsRedundantFilter 使用嵌入向量过滤冗余文档，通过比较文档间的语义相似度（基于余弦相似度）移除过于相似的文档。它比 EmbeddingsClusteringFilter 更简单，直接基于相似度阈值过滤。

核心功能

• 相似度过滤：根据嵌入向量的余弦相似度移除相似文档。
• 阈值控制：用户指定相似度阈值（如 0.8），高于阈值的文档被移除。
• 支持自定义嵌入：使用用户提供的嵌入模型。
• 批量处理：处理多个文档，返回过滤后的文档列表。

核心属性与方法

• 属性：
  • embeddings：嵌入模型实例（如 OpenAIEmbeddings）。
  • similarity_threshold：float，相似度阈值（0 到 1）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：过滤冗余文档。

使用方式与代码示例

from langchain_community.document_transformers import EmbeddingsRedundantFilter
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="量子计算很酷。"),
    Document(page_content="量子计算非常有趣。"),
    Document(page_content="经典计算很稳定。")
]

# 初始化嵌入模型和转换器
embeddings = OpenAIEmbeddings(api_key="your-api-key")
transformer = EmbeddingsRedundantFilter(embeddings=embeddings, similarity_threshold=0.8)

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print([doc.page_content for doc in transformed_docs])

输出：

['量子计算很酷。', '经典计算很稳定。']

说明：

• 移除与“量子计算很酷”相似度高于 0.8 的文档。

应用场景

• 文档去重：从搜索结果中移除重复内容。
• RAG 优化：减少检索中的冗余文档。
• 数据预处理：清洗数据集，保留多样性。

优化建议

• 调整阈值：根据任务设置合适的 similarity_threshold（如 0.7-0.9）。
• 高效嵌入：使用轻量级嵌入模型（如 SentenceTransformers）。
• 预计算嵌入：缓存嵌入向量，减少重复计算。

注意事项

• 依赖嵌入模型：需安装嵌入模型。
• 阈值选择：阈值过高可能保留过多冗余，过低可能误删有用文档。
• 性能问题：对大量文档进行两两比较可能耗时。

---

7. GoogleTranslateTransformer

定义

GoogleTranslateTransformer 使用 Google Cloud Translate API 将文档内容翻译为指定语言。它适合需要高质量翻译的场景，依赖 Google Cloud 服务。

核心功能

• 文本翻译：将文档内容翻译到目标语言。
• 语言检测：自动检测源语言（可选）。
• 批量处理：处理多个文档，返回翻译后的文档列表。
• 元数据保留：保持原始元数据。

核心属性与方法

• 属性：
  • target_language：str，目标语言代码（如 "es"）。
  • project_id：str，Google Cloud 项目 ID。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：翻译文档内容。

使用方式与代码示例

from langchain_community.document_transformers import GoogleTranslateTransformer
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="Quantum computing is exciting.")
]

# 初始化转换器
transformer = GoogleTranslateTransformer(target_language="es", project_id="your-project-id")

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].page_content)

输出：

La computación cuántica es emocionante.

说明：

• 将英文内容翻译为西班牙语。

应用场景

• 多语言支持：为全球用户提供翻译文档。
• RAG 系统：翻译检索文档以匹配用户语言。
• 数据增强：生成多语言训练数据。

优化建议

• 批量翻译：一次性处理多个文档，减少 API 请求。
• 缓存翻译：存储常见翻译结果，避免重复调用。
• 标准语言代码：使用 ISO 639-1 语言代码。

注意事项

• 依赖 Google Cloud：需配置 Google Cloud 凭据和安装 google-cloud-translate。
• 成本管理：API 调用可能产生费用，需监控使用量。
• 翻译质量：复杂文本可能需要人工校对。

---

8. Html2TextTransformer

定义

Html2TextTransformer 使用 html2text 库将 HTML 文档转换为纯文本。它专注于从 HTML 中提取文本内容，移除标签和格式。

核心功能

• HTML 转文本：将 HTML 内容转换为纯文本。
• 格式保留：可选保留部分格式（如换行、列表）。
• 批量处理：处理多个文档，返回转换后的文档列表。
• 元数据保留：保持原始元数据。

核心属性与方法

• 属性：
  • ignore_links：bool，是否忽略超链接（默认 True）。
  • ignore_images：bool，是否忽略图像（默认 True）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：转换 HTML 为文本。

使用方式与代码示例

from langchain_community.document_transformers import Html2TextTransformer
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="<p>这是正文</p><a href='#'>链接</a>")
]

# 初始化转换器
transformer = Html2TextTransformer(ignore_links=True)

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].page_content)

输出：

这是正文

说明：

• 移除 HTML 标签和链接，仅保留正文。

应用场景

• 网页清洗：从 HTML 网页提取纯文本。
• RAG 预处理：为检索系统准备纯文本文档。
• 文本分析：为 NLP 任务清洗 HTML 数据。

优化建议

• 选择性保留格式：根据需要调整 ignore_links 和 ignore_images。
• 批量处理：一次性处理多个文档，优化性能。
• 预处理 HTML：先用其他工具（如 BeautifulSoup）清洗复杂 HTML。

注意事项

• 依赖 html2text：需安装 html2text 库。
• 格式丢失：部分复杂 HTML 格式可能无法保留。
• 编码问题：确保 HTML 文档使用正确编码。

---

9. LongContextReorder

定义

LongContextReorder 重新排序文档列表，以优化长上下文场景下的模型性能。它将重要文档（通常是最近或最相关文档）放置在列表开头或中间，减轻模型对长序列的注意力衰减。

核心功能

• 文档重排序：根据策略重新排列文档列表。
• 优化注意力：将关键文档置于模型注意力集中的位置。
• 支持自定义策略：用户可以定义排序逻辑（如基于元数据）。
• 批量处理：处理多个文档，返回重新排序的文档列表。

核心属性与方法

• 属性：
  • strategy：str，排序策略（如 "middle_out" 或 "recent_first"）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：重新排序文档。

使用方式与代码示例

from langchain_community.document_transformers import LongContextReorder
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="旧文档1", metadata={"timestamp": "2023-01-01"}),
    Document(page_content="旧文档2", metadata={"timestamp": "2023-02-01"}),
    Document(page_content="新文档", metadata={"timestamp": "2023-03-01"})
]

# 初始化转换器
transformer = LongContextReorder(strategy="recent_first")

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print([doc.page_content for doc in transformed_docs])

输出：

['新文档', '旧文档2', '旧文档1']

说明：

• 按时间戳排序，将最新文档放在开头。

应用场景

• 长上下文 RAG：优化检索结果排序，提升模型性能。
• 对话系统：将最近文档优先展示，增强上下文相关性。
• 数据分析：按时间或重要性排序文档。

优化建议

• 选择合适策略：根据任务选择排序策略（如基于时间或相关性）。
• 元数据支持：利用文档元数据（如时间戳）增强排序。
• 小规模测试：先在小数据集上测试排序效果。

注意事项

• 排序策略：需明确排序逻辑，否则可能影响结果质量。
• 文档数量：对少量文档排序可能效果不明显。
• 元数据依赖：某些策略需要元数据支持。

---

10. MarkdownifyTransformer

定义

MarkdownifyTransformer 使用 markdownify 库将 HTML 文档转换为 Markdown 格式。它保留 HTML 的结构化信息（如标题、列表）并生成易读的 Markdown。

核心功能

• HTML 转 Markdown：将 HTML 内容转换为 Markdown 格式。
• 结构保留：保持标题、段落、列表等结构。
• 批量处理：处理多个文档，返回转换后的文档列表。
• 元数据保留：保持原始元数据。

核心属性与方法

• 属性：
  • strip_tags：List[str]，要移除的 HTML 标签（默认空）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：转换 HTML 为 Markdown。

使用方式与代码示例

from langchain_community.document_transformers import MarkdownifyTransformer
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="<h1>标题</h1><p>这是正文</p>")
]

# 初始化转换器
transformer = MarkdownifyTransformer()

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].page_content)

输出：

# 标题

这是正文

说明：

• 将 HTML 转换为 Markdown，保留标题和段落结构。

应用场景

• 文档格式化：将网页内容转换为 Markdown，方便编辑。
• RAG 预处理：为检索系统准备结构化 Markdown 文档。
• 内容发布：生成 Markdown 格式的文章或文档。

优化建议

• 清洗 HTML：先用 BeautifulSoup 预处理复杂 HTML。
• 批量处理：一次性处理多个文档，优化性能。
• 验证输出：检查 Markdown 格式是否符合预期。

注意事项

• 依赖 markdownify：需安装 markdownify 库。
• 复杂 HTML：某些 HTML 结构可能转换不完整。
• 编码问题：确保 HTML 使用正确编码。

---

11. NucliaTextTransformer

定义

NucliaTextTransformer 使用 Nuclia 的文本处理服务对文档进行增强，如提取实体、关键词或总结。它依赖 Nuclia 的云端 API 进行处理。

核心功能

• 文本增强：提取实体、关键词或生成总结。
• 结构化输出：将增强结果存储在文档的 metadata 或内容中。
• 批量处理：处理多个文档，返回增强后的文档列表。
• 云端处理：利用 Nuclia 的 NLP 能力。

核心属性与方法

• 属性：
  • api_key：str，Nuclia API 密钥。
  • processing_type：str，处理类型（如 "entity_extraction"）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：增强文档内容。

使用方式与代码示例

from langchain_community.document_transformers import NucliaTextTransformer
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="Alice 在巴黎旅行。")
]

# 初始化转换器
transformer = NucliaTextTransformer(api_key="your-nuclia-api-key", processing_type="entity_extraction")

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].metadata)

输出：

{'entities': [{'text': 'Alice', 'type': 'PERSON'}, {'text': '巴黎', 'type': 'LOCATION'}]}

说明：

• 提取文档中的实体，存储在 metadata 中。

应用场景

• 实体提取：从文本中提取人名、地点等信息。
• 关键词分析：为 RAG 系统生成关键词元数据。
• 文本总结：生成文档的简短摘要。

优化建议

• 选择处理类型：根据需求选择合适的 processing_type。
• 批量调用：减少 API 请求次数，优化成本。
• 缓存结果：存储常见文档的处理结果。

注意事项

• 依赖 Nuclia：需注册 Nuclia 账户并获取 API 密钥。
• 网络依赖：需稳定网络连接调用云端 API。
• 成本管理：Nuclia 服务可能产生费用，需监控。

---

12. OpenAIMetadataTagger

定义

OpenAIMetadataTagger 使用 OpenAI 的语言模型为文档添加元数据标签（如主题、情绪、关键词）。它通过分析文档内容生成结构化元数据。

核心功能

• 元数据生成：为文档添加标签，如主题或情绪。
• 支持自定义标签：用户定义所需的标签类型。
• 批量处理：处理多个文档，返回更新后的文档列表。
• 模型驱动：利用 OpenAI 的 NLP 能力。

核心属性与方法

• 属性：
  • tags：List[Dict]，定义要生成的标签（如 [{"name": "topic", "type": "string"}]）。
  • model：使用的 OpenAI 模型（如 "gpt-4o"）。
• 方法：
  • transform_documents(documents: List[Document], **kwargs) -> List[Document]：生成元数据标签。

使用方式与代码示例

from langchain_community.document_transformers import OpenAIMetadataTagger
from langchain_core.documents import Document

# 创建示例文档
docs = [
    Document(page_content="量子计算非常有趣！")
]

# 定义标签
tags = [
    {"name": "topic", "type": "string", "description": "主题"},
    {"name": "sentiment", "type": "string", "description": "情绪"}
]

# 初始化转换器
transformer = OpenAIMetadataTagger(tags=tags, openai_api_key="your-api-key")

# 转换文档
transformed_docs = transformer.transform_documents(docs)
print(transformed_docs[0].metadata)

输出：

{'topic': '量子计算', 'sentiment': '积极'}

说明：

• 为文档生成主题和情绪标签，存储在 metadata 中。

应用场景

• 元数据增强：为 RAG 系统添加语义标签。
• 内容分类：根据主题或情绪分类文档。
• 搜索优化：通过标签提高检索精度。

优化建议

• 精确标签定义：提供清晰的标签描述，提高生成质量。
• 缓存结果：对于重复文档，缓存标签结果。
• 异步处理：使用异步方法处理大批量文档。

注意事项

• 依赖 OpenAI：需配置 API 密钥。
• 模型成本：生成标签可能产生费用。
• 标签质量：复杂文档可能生成不准确的标签，需验证。

---

13. get_stateful_documents

定义

get_stateful_documents 是一个函数（而非类），用于从状态ful的文档源（如数据库或流式数据）中获取文档。它支持增量处理，返回 Document 对象的迭代器，适合处理动态数据。

核心功能

• 动态文档获取：从状态ful源（如数据库）获取文档。
• 增量处理：支持流式或分批获取文档。
• 状态管理：跟踪已处理文档，避免重复。
• 与转换器配合：生成文档后可直接传递给其他转换器。

核心参数

• source：文档源（如数据库连接或流式 API）。
• state_manager：状态管理器，跟踪处理进度。
• batch_size：int，每次获取的文档数量。

使用方式与代码示例

from langchain_community.document_transformers import get_stateful_documents
from langchain_core.documents import Document

# 模拟数据库源
class MockDB:
    def fetch(self, offset, limit):
        return [{"id": i, "text": f"文档 {i}"} for i in range(offset, offset + limit)]

# 初始化源和状态管理器
db = MockDB()
state = {"last_offset": 0}

# 获取文档
docs = list(get_stateful_documents(source=db.fetch, state_manager=state, batch_size=2))
print([doc.page_content for doc in docs])

输出：

['文档 0', '文档 1']

说明：

• 从模拟数据库获取两篇文档，更新状态。

应用场景

• 动态数据处理：从数据库或 API 获取实时文档。
• 流式 RAG：为流式检索系统提供文档。
• 增量更新：处理不断更新的文档源。

优化建议

• 合理批次大小：根据源性能设置 batch_size。
• 状态持久化：将 state_manager 保存到数据库，确保断点续传。
• 错误处理：为源故障添加重试机制。

注意事项

• 源兼容性：确保 source 支持分页或流式访问。
• 状态一致性：避免多进程修改 state_manager。
• 性能瓶颈：源的响应速度可能影响效率。

---

总结

以下是每个类和函数的简要总结：

类/函数	功能	主要应用场景	依赖
BeautifulSoupTransformer	清洗 HTML，提取/移除标签	网页清洗、RAG 预处理	beautifulsoup4
DoctranPropertyExtractor	提取属性（如人名、日期）	信息提取、元数据增强	doctran, OpenAI
DoctranQATransformer	生成问答对	问答数据集、RAG 增强	doctran, OpenAI
DoctranTextTranslator	翻译文档内容	多语言 RAG、国际化	doctran, OpenAI
EmbeddingsClusteringFilter	聚类过滤冗余文档	文档去重、RAG 优化	嵌入模型
EmbeddingsRedundantFilter	相似度过滤冗余文档	文档去重、RAG 优化	嵌入模型
GoogleTranslateTransformer	翻译文档内容	多语言支持、数据增强	Google Cloud Translate
Html2TextTransformer	HTML 转纯文本	网页清洗、文本分析	html2text
LongContextReorder	重新排序文档	长上下文 RAG、对话系统	无
MarkdownifyTransformer	HTML 转 Markdown	文档格式化、内容发布	markdownify
NucliaTextTransformer	文本增强（实体提取等）	实体提取、关键词分析	Nuclia API
OpenAIMetadataTagger	添加元数据标签	元数据增强、内容分类	OpenAI
get_stateful_documents	从状态ful源获取文档	动态数据处理、流式 RAG	无

优化共性建议：

• 使用异步方法处理大批量文档。
• 缓存中间结果，减少 API 调用或计算开销。
• 验证输出质量，特别是在使用外部模型或服务时。

注意共性事项：

• 确保安装所需依赖（如 beautifulsoup4、doctran）。
• 注意外部服务（如 OpenAI、Google Cloud）的成本。
• 处理复杂文档或动态数据时，需添加错误处理机制。