把帮助文档灌进 Pinecone 向量知识库

原文要点

原文是免费n8n模板：手动触发运行，从config节点的DOC_URLS读取公开帮助页地址（或回落到内置演示文档），带重试抓取并把HTML转纯文本，失败或文本过短的页面会被记录。文档按重叠窗口切块并生成稳定块ID，重跑时更新已有向量而非重复写入。预览模式或未配置时只输出将写入的切块不落库；正式模式批量调OpenAI Embeddings生成向量，失败的批次跳过，成功批次带标题、来源、块文本元数据upsert进Pinecone，最后报告写入条数或错误。

这次做成什么

把一批公开帮助文档切块、嵌入、写入Pinecone，给检索类客服机器人搭好向量底座，并学会用预览模式先验切块质量。

准备什么

• 可运行n8n云端或自托管实例的账号
• OpenAI API密钥，用于Embeddings接口
• Pinecone账号和一个维度与EMBED_DIMENSIONS一致（原文默认1536）的索引及Api-Key
• 若干公开可访问的帮助文档URL，或先用内置演示文档
• 对要灌入的文档有使用和转载的合法权利

具体怎么做

1. 首次预览跑通

   手动执行工作流，保持config节点中预览/测试状态（如TEST_RUN为true），不填DOC_URLS，让它用内置演示文档跑一遍。在输出里检查切块数量、每块字数和块ID是否稳定，确认切块逻辑符合预期。

2. 接入OpenAI与Pinecone

   添加OpenAI API凭据并把USE_OPENAI设为true；在Pinecone创建维度1536的索引，添加Header Auth（Api-Key）凭据，在config节点填PINECONE_INDEX_HOST和PINECONE_NAMESPACE。字段名以导入后config节点实际内容为准。

3. 填入自己的文档URL

   把公开帮助页URL逐行填入DOC_URLS，按文档平均长度调整CHUNK_WORDS与CHUNK_OVERLAP：FAQ类短文用较小块（如200词、重叠40词），长篇指南用较大块。先在预览模式看新切块是否过碎或过长。

4. 正式写入并验证

   把TEST_RUN设为false后手动运行，观察输出报告的upsert条数与被跳过的失败页列表。到Pinecone控制台抽查几条向量的metadata，确认title、source、chunk text齐全。重跑一次确认计数稳定、没有重复向量。

可直接复制的材料

{"TEST_RUN": true, "USE_OPENAI": true, "DOC_URLS": ["https://docs.example.com/help/billing", "https://docs.example.com/help/account"], "CHUNK_WORDS": 250, "CHUNK_OVERLAP": 50, "EMBED_MODEL": "text-embedding-3-small", "EMBED_DIMENSIONS": 1536, "PINECONE_INDEX_HOST": "your-index-xxxx.svc.pinecone.io", "PINECONE_NAMESPACE": "kb-v1"}

{"url": "https://docs.example.com/help/billing", "title": "发票与退款常见问题", "text": "电子发票在订单完成后24小时内自动开具，可在订单中心的发票管理中下载。发票抬头填写错误时，可在发票管理中申请重新开具，原发票将自动作废，新发票1-2个工作日内发送至注册邮箱。订阅服务支持随时取消，取消后在当前计费周期结束前仍可正常使用，已支付费用按未使用天数比例退还至原支付渠道，退款到账时间为3-7个工作日。企业用户如需增值税专用发票，请在账户设置中提交营业执照信息并选择纸质发票邮寄。"}

输入与输出示例

本站虚构演示，未真实运行；块数和字数取决于你的CHUNK_WORDS设置与原文切块实现。

输入

把上面的合成文档URL放入DOC_URLS，CHUNK_WORDS=120、CHUNK_OVERLAP=30，预览模式手动运行一次。

对应输出

预览输出示例（不落库）：[{"chunk_id": "billing-0", "title": "发票与退款常见问题", "source": "https://docs.example.com/help/billing", "words": 118, "text_preview": "电子发票在订单完成后24小时内自动开具……新发票1-2个工作日内发送至注册邮箱。"},{"chunk_id": "billing-1", "title": "发票与退款常见问题", "source": "https://docs.example.com/help/billing", "words": 96, "text_preview": "……取消后在当前计费周期结束前仍可正常使用，已支付费用按未使用天数比例退还……纸质发票邮寄。"}]

做完检查这些

• 预览模式只输出切块列表，Pinecone控制台确认没有任何向量被写入
• 同一文档重跑后块ID不变，Pinecone中向量总数不增加（更新而非重复）
• 正式模式输出的upsert计数与成功嵌入批次的块数一致，失败页在报告中被列出
• 抽查向量metadata含title、source、chunk text三个字段且值正确

容易卡住的地方

• 索引维度与EMBED_DIMENSIONS不匹配会导致upsert直接失败
• 受登录墙或反爬保护的页面会抓取失败，该模板只处理公开URL
• CHUNK_OVERLAP设得过大（接近CHUNK_WORDS）会产生大量近似重复的块
• 嵌入大批文档时OpenAI按token计费，先小批量试跑估算成本
• 原文说明嵌入失败的批次会被跳过，需看报告补跑，不会自动无限重试