企业官网建设流程全解析

1. 解析成功却检索不到：RAG 入库链路的可观测性盲区

如果你正在做 RAG 或 Agent 的文档入库，大概率遇到过这种场景：解析日志显示status: success，Markdown 文件也生成了，但用户提问时检索结果要么为空，要么答非所问。翻遍解析器日志找不到报错，最后发现是分块把表格切碎了、向量化时页码元数据丢了、或者入库写入的 collection 和检索用的不是同一个。

这类问题的根源在于：“解析成功”只是一个弱信号。它只说明解析器没有抛异常，不代表下游链路拿到了可用的上下文。RAG 的检索质量取决于从解析、分块、向量化到入库每一个环节的数据完整性，而大多数团队只监控了第一个环节。

我试过在一个科研文档入库项目里排查类似问题，最终定位到是分块阶段把跨页表格的页眉当成了正文，导致 chunk 里混入了大量噪声。如果当时有完整的链路埋点和 trace 记录，这个问题五分钟就能定位，而不是花了两天逐环节打印日志。

本文聚焦一个具体场景：文档解析成功但检索异常时，如何从可观测性角度拆解解析、分块、向量化、入库各环节，并通过统一的 Key/API 通道验证链路完整性。你会看到可复制的config.toml与settings.json骨架、埋点位置、验证请求的具体动作，以及常见错误的排查路径。适合正在搭建 RAG 入库管线、或者已经被“解析成功但检索失效”困扰的工程师。

2. TaoToken 前置：统一 Key 与 API 通道在入库链路中的位置

在拆解可观测性之前，先说明 TaoToken 在这个链路里扮演什么角色。RAG 入库管线通常涉及多个模型调用点：解析后的文本可能需要用 embedding 模型向量化，分块质量可能需要用 LLM 做校验，Agent 工具调用需要统一的模型入口。如果每个环节用不同的 Key、不同的 base_url、不同的超时配置，排查问题时你甚至无法确定是哪个通道出了问题。

TaoToken 在这里的价值是提供统一的 API 通道和 Key 管理，让入库链路的每个模型调用点都走同一个入口。这样当检索异常时，你可以先排除“是不是某个环节的 API 调用失败了”这个变量，把注意力集中在数据流本身。

具体来说，入库链路中至少有三个位置需要模型调用：

第一个是向量化环节，解析后的 chunk 需要调用 embedding 接口生成向量。第二个是分块质量校验，可以用 LLM 判断某个 chunk 是否语义完整、是否包含有效信息。第三个是Agent 工具调用，如果你的入库流程本身是一个 Agent 任务，解析工具、校验工具、入库工具的调用都需要模型支持。

这三个位置如果各自配置不同的 Key 和 endpoint，排查时你需要分别验证。统一走 TaoToken 的 API 通道后，你只需要在一个地方检查 Key 是否有效、额度是否充足、模型是否可用。

获取 Key 的入口在控制台的 API Keys 页面，模型对话调试可以用模型对话页面快速验证通道是否正常。如果你在做长期的编码或 Agent 任务，Coding Plan 提供了更稳定的调用配额。接入文档在 doc 页面有完整的参数说明。

需要强调的是，TaoToken 不替代你的解析器、不替代向量数据库、也不替代 RAG 框架。它解决的是“模型调用通道统一”这个问题，让你在排查入库链路时少一个变量。

3. 可复制配置：config.toml 与 settings.json 骨架

下面给出一个可复制的配置骨架，覆盖解析、分块、向量化、入库四个环节的埋点参数。你可以根据自己的技术栈替换具体的解析器和向量库，但 trace schema 和埋点位置建议保留。

3.1 config.toml：解析与分块阶段的观测配置

# config.toml - RAG 入库链路观测配置 [parse] # 解析器入口类型：cli / open_api / python_sdk / mcp_server entrypoint = "python_sdk" # 解析模式：pipeline / vlm / html model_version = "vlm" # 页码范围，空字符串表示全部 page_ranges = "1-50" # 输出格式 outputs = ["markdown", "json", "assets"] # 是否启用 OCR enable_ocr = true # OCR 语言 ocr_lang = "ch" # 超时秒数 timeout = 600 # 失败重试上限 max_retries = 2 [parse.trace] # trace 记录输出目录 trace_dir = "./runs/traces" # 是否记录源文件哈希 record_source_hash = true # 是否记录失败页 record_failure_pages = true [chunk] # 分块策略 strategy = "recursive" # chunk 大小（字符数） chunk_size = 1200 # 重叠大小 chunk_overlap = 180 # 是否按页切分 split_by_page = true # 是否保留元素类型元数据 keep_element_type = true # 是否保留页码元数据 keep_page_number = true # 是否保留来源 trace_id keep_trace_id = true [chunk.quality_check] # 是否启用 LLM 分块质量校验 enabled = true # 校验模型 model = "gpt-4o-mini" # 校验 prompt 模板路径 prompt_template = "./prompts/chunk_quality.txt" # 单次校验最大 chunk 数 max_chunks_per_batch = 20 [embedding] # 向量化模型 model = "text-embedding-3-small" # API 通道（统一走 TaoToken） base_url = "https://taotoken.net/api" # 批量大小 batch_size = 64 # 超时秒数 timeout = 120 # 失败重试上限 max_retries = 3 [vector_store] # 向量库类型 type = "chroma" # collection 名称（必须与检索端一致） collection_name = "rag_docs_v1" # 持久化目录 persist_dir = "./data/chroma" # 距离度量 metric = "cosine" [observability] # 是否启用全链路 trace enable_trace = true # trace 采样率（1.0 表示全量） sample_rate = 1.0 # 是否记录 chunk 内容哈希 record_chunk_hash = true # 是否记录 embedding 向量维度 record_embedding_dim = true # 敏感字段过滤列表 sensitive_fields = ["customer_name", "id_number", "contract_amount"]

这个配置的关键点在于：[chunk]段强制保留了page_number、element_type、trace_id三个元数据，这是后续检索能回溯到解析证据的基础。[observability]段的record_chunk_hash和record_embedding_dim用于验证向量化环节是否真的执行了，而不是静默跳过。

3.2 settings.json：API 通道与 Key 管理

{ "api_channels": { "default": { "base_url": "https://taotoken.net/api", "api_key_env": "TAOTOKEN_API_KEY", "timeout": 120, "max_retries": 3 }, "embedding": { "base_url": "https://taotoken.net/api", "api_key_env": "TAOTOKEN_API_KEY", "model": "text-embedding-3-small", "batch_size": 64 }, "llm_check": { "base_url": "https://taotoken.net/api", "api_key_env": "TAOTOKEN_API_KEY", "model": "gpt-4o-mini", "temperature": 0 } }, "trace_schema": { "trace_id": "string", "doc_id": "string", "source_hash": "string", "entrypoint": "string", "model_version": "string", "page_ranges": "string", "outputs": "array", "chunk_count": "integer", "embedding_dim": "integer", "collection_name": "string", "review_status": "string", "failure_type": "string", "failure_pages": "array" }, "ingestion_pipeline": { "steps": [ "parse", "chunk", "quality_check", "embed", "upsert", "verify" ], "fail_fast": false, "record_intermediate": true } }

settings.json的核心设计是所有模型调用走同一个base_url和同一个环境变量 Key。这样当检索异常时，你可以先用一个简单的验证请求确认通道是否正常，排除 API 层面的问题。

trace_schema定义了入库账本的最小字段集。每次入库任务生成一条 trace 记录，包含从解析到入库的所有关键参数和结果。ingestion_pipeline.steps定义了链路的六个阶段，record_intermediate: true表示每个阶段的中间产物都要记录，方便定位问题发生在哪一步。

4. 验证请求：用统一通道确认入库链路完整性

配置写好后，下一步是验证。验证分两层：先确认 API 通道本身正常，再确认入库链路的每个环节都产出了预期数据。

4.1 第一步：验证 API 通道

在排查入库问题之前，先用一个最小请求确认 TaoToken 通道可用。这一步排除的是“Key 失效、额度耗尽、模型不可用”这类基础问题。

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 5 }'

如果返回正常，说明通道没问题。如果返回 401，检查 Key 是否过期；返回 429，检查额度；返回 404，检查模型名是否正确。这一步通过后，再进入入库链路的验证。

4.2 第二步：验证解析输出

解析完成后，不要只看 Markdown 是否非空。至少检查以下五项：

import json from pathlib import Path def verify_parse_output(run_dir: str, trace_id: str): run_path = Path(run_dir) checks = {} # 1. Markdown 非空且长度合理 md_files = list(run_path.glob("*.md")) checks["markdown_exists"] = len(md_files) > 0 if md_files: content = md_files[0].read_text(encoding="utf-8") checks["markdown_length"] = len(content) checks["markdown_not_empty"] = len(content) > 100 # 2. JSON 结构存在且包含元素级信息 json_files = list(run_path.glob("*.json")) checks["json_exists"] = len(json_files) > 0 if json_files: data = json.loads(json_files[0].read_text(encoding="utf-8")) checks["json_has_pages"] = "pages" in data or "elements" in data # 3. 图片资产目录存在 asset_dirs = list(run_path.glob("assets")) + list(run_path.glob("images")) checks["assets_exist"] = len(asset_dirs) > 0 # 4. 失败页记录 fail_log = run_path / "failures.json" if fail_log.exists(): failures = json.loads(fail_log.read_text(encoding="utf-8")) checks["failure_count"] = len(failures) checks["failure_pages"] = [f.get("page") for f in failures] else: checks["failure_count"] = 0 # 5. trace_id 写入 checks["trace_id"] = trace_id return checks result = verify_parse_output("./runs/paper_001", "parse_20260724_001") print(json.dumps(result, ensure_ascii=False, indent=2))

这一步的输出会告诉你：解析到底产出了什么、有没有失败页、JSON 里有没有元素级结构。如果json_has_pages为 false，说明解析器没有输出结构化信息，后续分块只能靠纯文本切分，表格和公式大概率会丢。

4.3 第三步：验证分块元数据

分块是 RAG 入库最容易出问题的环节。验证的核心是：每个 chunk 是否携带了足够的元数据用于检索回溯。

def verify_chunks(chunks: list, trace_id: str): checks = { "total_chunks": len(chunks), "chunks_with_page": 0, "chunks_with_element_type": 0, "chunks_with_trace_id": 0, "empty_chunks": 0, "oversized_chunks": 0, } for chunk in chunks: meta = chunk.get("metadata", {}) text = chunk.get("text", "") if meta.get("page_number") is not None: checks["chunks_with_page"] += 1 if meta.get("element_type"): checks["chunks_with_element_type"] += 1 if meta.get("parse_trace_id") == trace_id: checks["chunks_with_trace_id"] += 1 if len(text.strip()) < 20: checks["empty_chunks"] += 1 if len(text) > 3000: checks["oversized_chunks"] += 1 checks["page_coverage"] = checks["chunks_with_page"] / max(checks["total_chunks"], 1) checks["trace_coverage"] = checks["chunks_with_trace_id"] / max(checks["total_chunks"], 1) return checks

如果page_coverage低于 0.9，说明大部分 chunk 丢失了页码信息，检索时无法回溯到原文页。如果empty_chunks大于 0，说明分块策略把空白内容也切进去了，这些 chunk 会污染检索结果。

4.4 第四步：验证向量化与入库

向量化环节的验证重点是：embedding 是否真的执行了、维度是否正确、写入的 collection 是否与检索端一致。

def verify_embedding_and_upsert(chunks: list, collection_name: str, vector_store): checks = { "chunks_to_embed": len(chunks), "embedding_dim": None, "collection_name": collection_name, "upserted_count": 0, "collection_count": 0, } # 抽样检查第一个 chunk 的向量维度 if chunks: sample_vector = chunks[0].get("embedding") if sample_vector: checks["embedding_dim"] = len(sample_vector) # 检查向量库中的实际数量 try: checks["collection_count"] = vector_store.count(collection_name) except Exception as e: checks["collection_error"] = str(e) return checks

关键对比：chunks_to_embed和collection_count应该接近。如果collection_count远小于chunks_to_embed，说明 upsert 阶段有大量数据丢失。如果embedding_dim为 None，说明向量化根本没执行，chunk 直接进了库。

4.5 第五步：端到端检索验证

最后一步是用一个已知答案的问题去检索，确认能命中预期 chunk。

def verify_retrieval(query: str, expected_page: int, vector_store, collection_name: str): results = vector_store.query( collection_name=collection_name, query_texts=[query], n_results=5 ) hits = [] for i, meta in enumerate(results["metadatas"][0]): hits.append({ "rank": i + 1, "page": meta.get("page_number"), "element_type": meta.get("element_type"), "trace_id": meta.get("parse_trace_id"), "distance": results["distances"][0][i] if "distances" in results else None, }) expected_hit = any(h["page"] == expected_page for h in hits) return {"query": query, "expected_page": expected_page, "expected_hit": expected_hit, "hits": hits}

如果expected_hit为 false，但解析和分块都正常，问题可能出在 embedding 模型与检索 query 的语义空间不匹配，或者向量库的距离度量配置有误。

5. 本篇常见错排查：解析成功但下游失效的六种典型

5.1 分块把表格切碎导致检索命中率低

现象：解析输出的 Markdown 里表格完整，但检索时表格相关问题答不出来。排查方法：检查 chunk 的element_type元数据，如果表格被切成了多个paragraph类型的 chunk，说明分块策略没有识别表格边界。解决方式是在分块前先用 JSON 结构标记表格区域，对表格区域采用整块保留策略。

5.2 页码元数据在分块阶段丢失

现象：检索能命中相关 chunk，但无法回溯到原文页码，引用来源显示为“未知”。排查方法：运行 4.3 节的verify_chunks，检查page_coverage。如果低于 0.9，说明分块器没有继承解析阶段的页码信息。解决方式是在分块器的 metadata 传递逻辑里显式保留page_number字段。

5.3 向量化静默跳过

现象：入库日志显示成功，但向量库 count 为 0 或远小于 chunk 数。排查方法：运行 4.4 节的验证，对比chunks_to_embed和collection_count。常见原因是 embedding 接口返回了错误但被 catch 后静默忽略，或者 batch_size 设置过大导致部分请求超时未重试。

5.4 collection 名称不一致

现象：入库写入的是rag_docs_v1，检索查询的是rag_docs，两边都正常但就是查不到。排查方法：在入库和检索两端分别打印 collection 名称。这个错误在配置分散管理时特别常见，建议把 collection 名称放在统一的配置中心。

5.5 embedding 模型与检索 query 不匹配

现象：入库用的是text-embedding-3-small，检索时 query 用了另一个模型或另一个维度。排查方法：检查入库和检索两端的 embedding 模型配置。不同模型的向量空间不兼容，混用会导致检索结果完全随机。

5.6 API 通道超时导致部分 chunk 未向量化

现象：大批量入库时，部分 chunk 的 embedding 请求超时，但流程没有中断，最终入库数量少于预期。排查方法：在 trace 记录里增加embedding_failures字段，记录超时和重试次数。解决方式是在向量化环节增加失败队列，超时的 chunk 进入重试队列而不是直接丢弃。

6. 语义一致 CTA：把可观测性落到你的入库管线里

排查入库链路问题的核心思路是：不要相信“解析成功”这个单一信号，要在每个环节留下可验证的痕迹。本文给出的config.toml和settings.json骨架可以直接复制到你的项目里，trace schema 和验证脚本可以根据你的技术栈调整。

如果你在接入过程中遇到 API 通道相关的问题，可以先到 API Keys 页面确认 Key 状态，接入文档 里有完整的参数说明和错误码对照。如果你想先快速验证模型通道是否正常，模型对话页面可以做一个最小请求测试。长期做编码或 Agent 任务的，Coding Plan 提供了更稳定的调用配额。

最后给一个实用建议：把失败集当成资产来维护。每次排查出的问题，记录 trace_id、失败类型、期望结果和实际结果，形成回归测试集。下次升级解析器、调整分块策略或更换 embedding 模型时，先跑一遍失败集，比重新抽样验收高效得多。