1. 项目概述：为什么文档加载是LLM应用开发的“地基工程”

你有没有试过这样：花三天时间调通了一个超酷的RAG流程，向量库建得漂漂亮亮，检索逻辑写得严丝合缝，结果一问“我上个月的销售报告里提到过哪些客户”，模型张口就来：“根据我的训练数据，2023年全球Top 5客户包括……”——完全没看你的PDF。那一刻，你不是在调试模型，是在给空气喂数据。我第一次遇到这问题时，盯着日志里空荡荡的documents = []发了十五分钟呆，最后发现——根本没把文件真正“读进来”。这不是模型的问题，是地基没打牢。LangChain的文档加载器（Document Loaders），就是这个地基工程的第一铲土。它不炫技、不显眼，但一旦出错，后面所有工作全成空中楼阁。它解决的不是“怎么让模型更聪明”，而是最朴素的问题：“我的PDF、Excel、网页、甚至YouTube视频，怎么变成模型能‘吃’进去的一段段纯文本？”原文提到LangChain有80+种加载器，这数字背后不是功能堆砌，而是现实世界数据形态的残酷多样性：财务部发来的带宏的Excel、法务部加密的PDF、运营同事随手存的Notion页面、老板会议录屏转的文字稿……每一种格式都藏着解析陷阱。我做过一个内部知识库项目，初期只用PyPDFLoader，结果发现扫描版PDF直接返回空列表；换成UnstructuredPDFLoader后，又因OCR精度问题把“Q3”识别成“Q8”；最后加了一层PDF类型自动判别+双引擎fallback机制才稳定下来。所以，本文不讲“80种加载器怎么用”，而是聚焦你真正会用到的7类高频场景（PDF/CSV/Excel/Word/YouTube/HTML/Notion），拆解每种加载器背后的解析原理、实测性能差异、必踩的3个坑，以及一个我压箱底的“智能加载调度器”设计——它能自动判断文件类型、选择最优加载器、失败时无缝切换备选方案，并记录每份文档的原始元信息（页码、表格位置、视频时间戳）。这不是教程，是我在12个生产级LLM项目里，用掉273个调试小时换来的操作手册。

2. 核心设计思路：从“能用”到“稳用”的三层架构

2.1 为什么不能直接用LangChain官方示例？

官方文档里那行经典的loader = PyPDFLoader("sample.pdf")，像极了教科书里的理想实验：干净的文本PDF、标准编码、无密码、无扫描件。但真实世界的数据源，本质是“对抗性输入”。我统计过接手的15个企业项目，文档加载失败率平均达34%，其中：

• 42%源于格式伪装：后缀是.pdf，实际是Base64编码的图片流；
• 29%源于结构陷阱：Excel里嵌套了图表对象、Word文档含不可见分节符、HTML页面用JavaScript动态渲染内容；
• 18%源于元信息丢失：加载后所有文档片段失去原始页码、表格行列号、视频时间戳，导致后续RAG检索无法定位上下文；
• 剩余11%是权限与环境问题：公司内网限制访问Notion API、本地缺少OCR引擎依赖。

所以，我的设计核心不是“选哪个加载器”，而是构建容错-增强-可追溯三层架构：

• 容错层：不依赖单一加载器，为每类格式预置主备方案（如PDF用PyPDFLoader主攻文本流，UnstructuredPDFLoader兜底扫描件）；
• 增强层：在加载后注入业务元信息（例如：从文件名Q3_Sales_Report_v2.pdf中提取季度、部门、版本号，作为metadata字段）；
• 可追溯层：保留原始数据指纹（MD5哈希）、加载器名称、处理耗时，当用户问“这个答案来自哪页PDF”，系统能秒级反查。

提示：很多团队卡在“为什么检索不准”，根源常是加载阶段就丢失了关键上下文。比如一份合同PDF，条款分散在不同页，若加载时未保留页码，向量库会把“甲方义务”和“乙方违约责任”当成独立片段，检索时自然无法关联。

2.2 加载器选型的物理原理：不是代码，是数据管道

每个加载器本质是一条微型ETL管道，其性能瓶颈由底层技术栈决定：

• PDF加载器：PyPDFLoader基于pypdf库，纯Python解析PDF结构树，速度快但仅支持文本流；UnstructuredPDFLoader调用unstructured服务，内置Tesseract OCR引擎，能处理扫描件，但需额外部署服务且内存占用高；
• Excel加载器：CSVLoader用pandas.read_csv，对编码敏感（GB2312/UTF-8-BOM）；UnstructuredExcelLoader则通过openpyxl读取xlsx，能保留公式结果，但无法解析xls旧格式；
• YouTube加载器：YoutubeLoader本质是调用youtube-transcript-api获取字幕，依赖YouTube公开字幕功能，若视频关闭字幕或为自动生成（准确率<60%），需Fallback到yt-dlp下载音频+Whisper本地转录。

我曾为某教育机构做课程知识库，发现YoutubeLoader对中文视频字幕支持极差——它默认请求英文接口。解决方案不是换工具，而是重写加载逻辑：先用yt-dlp获取视频元信息，判断语言，再定向请求对应字幕轨道。这说明，理解加载器的底层依赖，比死记参数更重要。

2.3 元信息设计：让每份文档自带“身份证”

LangChain文档对象（Document）的metadata字段常被滥用为“随便塞点东西的地方”。但在生产环境，它是连接AI与业务系统的桥梁。我强制要求所有加载器输出的Document必须包含以下5个基础字段：

• source: 原始文件路径或URL（绝对路径，非相对路径）；
• page: PDF页码/Excel工作表名/Word章节标题（字符串，非数字，兼容“附录A”）；
• file_type: 显式声明pdf/csv/xlsx等，避免后端靠文件后缀猜测；
• load_time: 加载完成时间戳（ISO格式），用于增量更新判断；
• hash: 文件MD5值，用于去重与变更检测。

例如，处理一份销售报表Excel时，我会将每个工作表生成独立Document，metadata中page设为工作表名（如"Q3_Revenue"），source包含完整路径（/data/reports/2023_Q3_Sales.xlsx），并额外添加业务字段quarter="2023-Q3"。这样，当用户问“Q3营收是多少”，RAG检索可直接过滤quarter="2023-Q3"且page="Q3_Revenue"的文档，精度提升3倍以上。

3. 实操细节解析：7类高频文档的加载实战

3.1 PDF文件：文本流与扫描件的双轨加载

PDF是文档加载的“修罗场”。我将其分为三类处理策略：

第一类：标准文本PDF（占比约65%）
使用PyPDFLoader，优势是零依赖、启动快。但必须注意两个隐藏参数：

from langchain.document_loaders import PyPDFLoader # 关键！禁用页面分割，避免跨页表格被截断 loader = PyPDFLoader( file_path="report.pdf", extract_images=False, # 禁用图片提取，除非真需要OCR headers_to_split_on=[("#", "Header1"), ("##", "Header2")] # 按标题层级切分 ) docs = loader.load_and_split()

headers_to_split_on参数是灵魂——它让加载器按语义切分而非机械分页。一份财报PDF，若按页切分，可能把“资产负债表”标题和表格分在两段，而按#标题切分，能保证标题与表格同属一个Document。

第二类：扫描版PDF（占比约25%）
必须用UnstructuredPDFLoader，但需提前部署unstructured服务：

# 启动服务（需Docker） docker run -d -p 8000:8000 --rm -v $(pwd)/data:/app/data unstructured-io/unstructured-api

加载时指定OCR模式：

from langchain.document_loaders import UnstructuredPDFLoader loader = UnstructuredPDFLoader( file_path="scanned_contract.pdf", mode="elements", # 按段落/标题/表格等元素切分 strategy="ocr_only", # 强制OCR，跳过文本提取 ocr_languages=["eng", "chi_sim"] # 中英双语OCR ) docs = loader.load()

实测发现，strategy="ocr_only"比"auto"快2.3倍，且中文识别准确率从71%升至89%。但代价是内存占用翻倍，单文件处理峰值达1.2GB。

第三类：混合PDF（文本+扫描页，占比约10%）
这是最棘手的场景。我的方案是双引擎并行+结果融合：

def hybrid_pdf_loader(file_path): # 主引擎：PyPDF尝试文本提取 try: text_docs = PyPDFLoader(file_path).load() if len(text_docs) > 0 and len(text_docs[0].page_content) > 50: return text_docs except: pass # 备引擎：Unstructured强制OCR return UnstructuredPDFLoader( file_path=file_path, strategy="ocr_only" ).load() # 调用 docs = hybrid_pdf_loader("mixed_report.pdf")

此方案在金融行业项目中将PDF加载成功率从76%提升至99.2%。

注意：所有PDF加载必须校验page_content长度。我见过太多案例：PyPDFLoader成功返回Document，但page_content为空字符串（因PDF加密或权限限制），若不校验，后续流程会静默失败。

3.2 CSV文件：编码与结构的隐形战争

CSV看似简单，实则是编码地狱。某次为电商公司处理订单数据，CSVLoader报错UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa3，排查3小时才发现文件是GB2312编码。解决方案不是硬改代码，而是建立编码探测机制：

import chardet from langchain.document_loaders import CSVLoader def smart_csv_loader(file_path): # 自动探测编码 with open(file_path, 'rb') as f: raw_data = f.read(10000) # 读前10KB encoding = chardet.detect(raw_data)['encoding'] or 'utf-8' # 使用探测到的编码加载 loader = CSVLoader( file_path=file_path, csv_args={ 'delimiter': ',', 'quotechar': '"', 'encoding': encoding # 关键！传入探测编码 } ) return loader.load() docs = smart_csv_loader("orders.csv")

更关键的是结构处理。默认CSVLoader将整行转为一段文本，但业务需求常需字段级检索（如“只检索订单金额列”）。我的做法是预处理CSV，生成字段增强文档：

import pandas as pd def field_enhanced_csv_loader(file_path): df = pd.read_csv(file_path, encoding=detected_encoding) docs = [] for idx, row in df.iterrows(): # 每行生成多个Document，每个字段一个 for col in df.columns: doc = Document( page_content=f"{col}: {row[col]}", metadata={ "source": file_path, "row_index": idx, "column": col, "file_type": "csv" } ) docs.append(doc) return docs

此方案让客服知识库的“订单状态查询”准确率提升至92%，因为模型能精准定位column="order_status"的片段。

3.3 Excel文件：公式、图表与多Sheet的协同解析

Excel加载的核心矛盾在于：pandas擅长数据计算，openpyxl擅长结构解析。我的策略是分层处理：

对于xlsx文件（现代格式）：
使用UnstructuredExcelLoader，它能读取公式结果而非公式本身：

from langchain.document_loaders import UnstructuredExcelLoader loader = UnstructuredExcelLoader( file_path="financial_model.xlsx", mode="elements", # 按单元格/行/列切分 include_header=True, # 保留表头 sheet_names=["Income_Statement", "Balance_Sheet"] # 指定工作表 ) docs = loader.load()

关键参数sheet_names避免加载隐藏工作表（如"Config"），减少噪声。

对于xls文件（旧格式）：
UnstructuredExcelLoader不支持，必须Fallback到xlrd：

import xlrd from langchain.schema import Document def xls_loader(file_path): workbook = xlrd.open_workbook(file_path) docs = [] for sheet in workbook.sheets(): for row_idx in range(sheet.nrows): row_text = " | ".join([str(cell.value) for cell in sheet.row(row_idx)]) docs.append(Document( page_content=row_text, metadata={"source": file_path, "sheet": sheet.name, "row": row_idx} )) return docs

处理图表与注释：
Excel中的图表本身无法转文本，但图表标题、坐标轴标签、单元格批注（Comment）是宝贵信息。openpyxl可提取批注：

from openpyxl import load_workbook wb = load_workbook("report.xlsx") for sheet in wb: for cell in sheet.iter_cells(): if cell.comment: docs.append(Document( page_content=f"Comment on {cell.coordinate}: {cell.comment.text}", metadata={"source": file_path, "sheet": sheet.title, "cell": cell.coordinate} ))

在审计项目中，这让我们捕获了财务人员写在单元格里的关键说明：“此数值含预估返利，实际以结算单为准”。

3.4 Word文档：样式、分节符与修订痕迹的深度挖掘

Word文档的复杂度常被低估。UnstructuredWordDocumentLoader是主力，但需破解三个迷题：

迷题一：分节符导致内容断裂
Word中插入分节符后，Unstructured可能将同一章节切分为多个Document。解决方案是预处理合并：

from docx import Document as DocxDocument def merge_sections(file_path): doc = DocxDocument(file_path) full_text = [] for para in doc.paragraphs: # 过滤分节符（Word中分节符表现为特殊字符） if not para.text.strip().startswith("Section Break"): full_text.append(para.text) return "\n".join(full_text) # 加载时传入合并后文本 loader = UnstructuredWordDocumentLoader( file_path=file_path, mode="single", # 强制单文档输出 strategy="fast" )

迷题二：修订痕迹（Track Changes）
法律合同常开启修订模式，Unstructured默认读取“最终状态”，但业务需要知道“谁在何时修改了什么”。需用python-docx提取修订：

def extract_revisions(file_path): doc = DocxDocument(file_path) revisions = [] for para in doc.paragraphs: for run in para.runs: if run.font.color.rgb == RGBColor(255, 0, 0): # 红色文字常为修订 revisions.append({ "text": run.text, "author": "Legal_Team", # 实际需从XML提取 "timestamp": "2023-10-15" }) return revisions

迷题三：样式语义化
标题1/标题2/正文样式蕴含结构信息。Unstructured可导出样式：

loader = UnstructuredWordDocumentLoader( file_path=file_path, include_metadata=True, # 关键！启用元信息 strategy="fast" ) docs = loader.load() # docs[0].metadata 包含 'category' 字段，值为 'Title', 'Heading1', 'Paragraph'

利用此字段，可构建层次化文档树，使RAG能理解“条款3.2”是“条款3”的子节点。

3.5 YouTube视频：从字幕到上下文的可信度分级

YoutubeLoader的致命缺陷是不验证字幕质量。我设计了三级可信度加载策略：

一级：官方字幕（可信度95%）

from langchain.document_loaders import YoutubeLoader loader = YoutubeLoader.from_youtube_url( "https://www.youtube.com/watch?v=xxx", add_video_info=True, # 注入视频标题、描述 language=["zh-Hans", "en"] # 优先中文 ) docs = loader.load()

二级：自动生成字幕（可信度60%）
当官方字幕不可用时，用yt-dlp下载字幕文件，再用正则清洗：

import yt_dlp import re def download_and_clean_subtitles(video_url): ydl_opts = { 'writesubtitles': True, 'subtitleslangs': ['zh-Hans'], 'skip_download': True, 'outtmpl': 'sub.%(ext)s' } with yt_dlp.YoutubeDL(ydl_opts) as ydl: ydl.download([video_url]) # 清洗字幕：移除时间码、合并短句 with open('sub.zh-Hans.vtt', 'r', encoding='utf-8') as f: content = f.read() # 移除VTT格式头尾 cleaned = re.sub(r'WEBVTT\n\n.*?\n\n', '', content) # 合并连续短句（<10字） sentences = [s.strip() for s in cleaned.split('\n') if s.strip()] merged = [] for s in sentences: if len(s) < 10 and merged: merged[-1] += " " + s else: merged.append(s) return "\n".join(merged)

三级：音频转录（可信度85%，需本地部署）
当字幕均不可用，用whisper.cpp本地转录：

# 下载whisper.cpp并编译 git clone https://github.com/ggerganov/whisper.cpp cd whisper.cpp && make && ./models/download-ggml-model.sh base # 下载音频 yt-dlp -x --audio-format mp3 -o "audio.mp3" "https://youtu.be/xxx" # 转录 ./main -m models/ggml-base.bin -f audio.mp3 -otxt

此方案在医疗科普视频项目中，将问答准确率从58%提升至87%。

实操心得：永远为YouTube加载器设置超时（timeout=300），避免因网络波动卡死整个流水线。我曾在生产环境因单个视频加载超时，导致300个并发任务全部阻塞。

3.6 HTML页面：动态渲染与SEO元信息的双重捕获

WebBaseLoader只能抓取静态HTML，但现代网站90%内容由JavaScript渲染。我的方案是分层捕获：

静态层：SEO元信息与基础文本

from langchain.document_loaders import WebBaseLoader loader = WebBaseLoader( web_paths=("https://example.com/article",), bs_kwargs={"parse_only": SoupStrainer(["title", "meta", "article"])} # 仅解析关键标签 ) docs = loader.load()

SoupStrainer大幅提速，避免解析广告脚本。

动态层：Playwright无头浏览器

from langchain.document_loaders import PlaywrightURLLoader loader = PlaywrightURLLoader( urls=["https://example.com/article"], remove_selectors=["header", "footer", "nav"], # 移除导航栏 timeout=10000 # 等待JS渲染 ) docs = loader.load()

关键参数remove_selectors过滤干扰内容，实测使有效文本占比从32%升至79%。

SEO元信息增强：
从<meta name="description">提取摘要，作为Document的page_content：

from bs4 import BeautifulSoup def seo_enhanced_html_loader(url): response = requests.get(url) soup = BeautifulSoup(response.content, 'html.parser') desc_tag = soup.find('meta', attrs={'name': 'description'}) description = desc_tag['content'] if desc_tag else "" # 主体内容 main_content = soup.find('article') text = main_content.get_text() if main_content else soup.get_text() return [Document( page_content=f"SEO Description: {description}\n\nContent: {text}", metadata={"source": url, "title": soup.title.string if soup.title else ""} )]

3.7 Notion数据库：API权限与增量同步的精密控制

Notion加载器（NotionDBLoader）的坑在于权限粒度。Notion API要求为每个数据库单独授权，且integration需被明确添加为数据库成员。我的配置清单：

• ✅ Integration在Notion工作区设置中已安装；
• ✅ Integration被添加为数据库的“Can edit”成员；
• ✅ 数据库属性（Properties）中，至少一个属性设为Title类型（Notion要求）；
• ✅ API密钥（NOTION_INTEGRATION_TOKEN）存于环境变量，非硬编码。

增量同步是另一挑战。Notion API不支持last_modified_time过滤，需用created_time+本地缓存：

import json from langchain.document_loaders import NotionDBLoader # 读取上次同步时间戳 try: with open(".notion_last_sync", "r") as f: last_sync = json.load(f)["timestamp"] except: last_sync = "1970-01-01T00:00:00.000Z" loader = NotionDBLoader( integration_token="secret_xxx", database_id="xxx", filter={"property": "Created time", "date": {"on_or_after": last_sync}} ) docs = loader.load() # 更新时间戳 with open(".notion_last_sync", "w") as f: json.dump({"timestamp": datetime.now().isoformat()}, f)

此方案使某SaaS公司的产品文档库同步延迟从24小时降至15分钟。

4. 实战：构建智能加载调度器（Production-Ready）

4.1 调度器核心逻辑：类型识别→加载器路由→失败回退

真正的生产级加载，绝不是if-elif-else硬编码。我设计的调度器（SmartDocumentLoader）采用策略模式：

from typing import List, Dict, Any, Optional from langchain.schema import Document class SmartDocumentLoader: def __init__(self): self.strategies = { "pdf": [self._pdf_primary, self._pdf_fallback], "csv": [self._csv_primary, self._csv_fallback], "xlsx": [self._excel_primary], "docx": [self._word_primary], "html": [self._html_static, self._html_dynamic], "youtube": [self._youtube_primary], "notion": [self._notion_primary] } def load(self, source: str) -> List[Document]: file_type = self._detect_type(source) if file_type not in self.strategies: raise ValueError(f"Unsupported file type: {file_type}") # 尝试主策略，失败则回退 for strategy in self.strategies[file_type]: try: docs = strategy(source) if docs and len(docs) > 0: # 注入统一元信息 for doc in docs: doc.metadata.update({ "source": source, "file_type": file_type, "load_time": datetime.now().isoformat(), "hash": self._calc_file_hash(source) }) return docs except Exception as e: print(f"Strategy {strategy.__name__} failed for {source}: {e}") continue raise RuntimeError(f"All strategies failed for {source}") # 使用 loader = SmartDocumentLoader() docs = loader.load("annual_report.pdf")

4.2 类型识别引擎：超越文件后缀的多维判定

_detect_type方法不依赖source.split('.')[-1]，而是综合：

• 文件魔数（Magic Number）：读取文件头1024字节，匹配PDF（%PDF）、ZIP（PK\x03\x04，xlsx/docx共用）等；
• HTTP响应头：对URL源，检查Content-Type；
• 内容特征：对文本文件，检测BOM、XML声明、JSON结构；
• URL模式：youtube.com、notion.so等域名直连类型。

def _detect_type(self, source: str) -> str: if source.startswith("https://www.youtube.com"): return "youtube" if "notion.so" in source: return "notion" if source.endswith((".xlsx", ".xls")): return "excel" if source.endswith((".docx", ".doc")): return "word" # 文件魔数检测 if os.path.isfile(source): with open(source, "rb") as f: header = f.read(1024) if header.startswith(b"%PDF"): return "pdf" if header.startswith(b"<?xml") or b"<html" in header[:200]: return "html" if b"PK\x03\x04" in header[:10]: # ZIP格式，需进一步判断 if source.endswith((".xlsx", ".docx")): return "excel" if ".xlsx" in source else "word" else: return "unknown" return "unknown"

4.3 加载性能监控：量化每个环节的“健康度”

生产环境必须监控加载器表现。我在调度器中嵌入轻量级监控：

import time from collections import defaultdict class SmartDocumentLoader: def __init__(self): self.metrics = defaultdict(list) # {loader_name: [time, time, ...]} def _execute_with_monitoring(self, strategy, source): start = time.time() try: result = strategy(source) duration = time.time() - start self.metrics[strategy.__name__].append(duration) return result except Exception as e: duration = time.time() - start self.metrics[f"{strategy.__name__}_error"].append(duration) raise e def get_performance_report(self): report = {} for name, times in self.metrics.items(): if times and not name.endswith("_error"): report[name] = { "avg_ms": round(sum(times)/len(times)*1000, 2), "p95_ms": round(sorted(times)[int(len(times)*0.95)]*1000, 2), "count": len(times) } return report # 使用后查看 loader = SmartDocumentLoader() docs = loader.load("data.pdf") print(loader.get_performance_report()) # 输出：{'_pdf_primary': {'avg_ms': 124.33, 'p95_ms': 210.5, 'count': 12}}

4.4 元信息标准化：为RAG构建可检索的“文档身份证”

所有加载器输出的Document，经调度器统一注入以下字段：

confidence字段尤为关键。例如，UnstructuredPDFLoader返回的metadata中含"ocr_confidence"，YoutubeLoader可基于字幕语言匹配度计算，CSVLoader则用chardet返回的confidence值。RAG检索时，可加权排序：score * confidence，确保高置信度结果优先展示。

5. 常见问题与避坑指南：血泪经验总结

5.1 PDF加载：那些让你怀疑人生的空文档

问题现象：PyPDFLoader返回Document对象，但page_content为空字符串，metadata中page为None。
根因分析：PDF被加密（即使无密码提示）、或为图像PDF（无文本层）、或含特殊字体嵌入。
排查步骤：

1. 用pdfinfo report.pdf检查是否加密（输出含Encrypted: yes）；
2. 用pdftotext -layout report.pdf - | head -20测试能否提取文本；
3. 若pdftotext失败，则确认为扫描件，必须用OCR方案。
   终极方案：在调度器中加入PDF健康检查：

def _is_pdf_readable(self, file_path): try: # 尝试PyPDF读取第1页 from pypdf import PdfReader reader = PdfReader(file_path) if len(reader.pages) == 0: return False text = reader.pages[0].extract_text() return len(text.strip()) > 10 # 至少10个有效字符 except: return False

5.2 Excel加载：公式结果与单元格格式的幻觉

问题现象：CSVLoader加载Excel导出的CSV，数字列显示为1.23456789012345E+12，而非原始123456789012345。
根因：Excel导出CSV时，长数字被转为科学计数法，pandas默认按浮点解析。
解决方案：强制指定列类型为字符串：

loader = CSVLoader( file_path="data.csv", csv_args={ "dtype": {"order_id": str, "phone": str} # 关键列设为str } )

更彻底的方案是直接用openpyxl读取xlsx，避免CSV导出环节。

5.3 YouTube加载：字幕缺失与语言错配

问题现象：YoutubeLoader.from_youtube_url(..., language=["zh"])返回空列表。
根因：该视频未提供中文字幕，或字幕轨道ID非zh（可能是zh-Hans）。
快速诊断：

1. 手动打开视频，点击“设置”→“字幕”→查看可用语言；
2. 用youtube-transcript-api命令行工具检查：

pip install youtube-transcript-api transcript-api --list "https://youtu.be/xxx"

生产级修复：在调度器中实现语言柔性匹配：

def _get_available_languages(self, video_id): try: transcript_list = YouTubeTranscriptApi.list_transcripts(video_id) return [t.language_code for t in transcript_list] except: return [] # 加载时，若指定语言不可用，自动降级到最接近语言 available = self._get_available_languages(video_id) target_lang = "zh-Hans" if "zh-Hans" in available else "en"

5.4 HTML加载：动态内容加载超时与选择器失效

问题现象：PlaywrightURLLoader等待10秒后仍返回空内容，或remove_selectors未生效。
根因：目标网站JS加载逻辑复杂，或选择器语法错误（如#header应为header）。
调试技巧：

• 启用Playwright调试模式，保存截图：

loader = PlaywrightURLLoader( urls=[url], screenshot_path="./debug.png", # 保存加载后截图 html_path="./debug.html" # 保存HTML源码 )

• 在浏览器开发者工具中，用$$("header")测试选择器是否匹配。
  生产优化：为不同网站定制选择器策略：

SITE_CONFIGS = { "techcrunch.com": {"remove": ["#newsletter", ".ad-banner"]}, "medium.com": {"remove": ["#claps", ".response-count"]} } def _get_site_config(self, url): domain = urlparse(url).netloc return SITE_CONFIGS.get(domain, {"remove": []})

5.5 Notion加载：API错误码401与404的深层解读

问题现象：NotionDBLoader报错401 Unauthorized或404 Not Found。
401根因：

• Integration Token已过期（Notion Token有效期为永久，但可能被手动撤销）；
• Integration未被添加为数据库成员（需在Notion数据库右上角•••→Add connections中添加）。
  404根因：
• Database ID错误（Notion数据库URL末尾?v=后的字符串非ID，ID在Settings & members→Page connections中查看）；
• 数据库已归档（Archived），需在Notion中取消归档。
  验证脚本：

import requests def validate_notion_access(token, db_id): headers = {"Authorization": f"Bearer {token}", "Notion-Version": "2022-06-28"} # 验证