语雀导入 OpenAI File Search：Markdown 导出、向量库分包与检索验收清单

OpenAI File Search 适合把产品文档、帮助中心、内部 SOP、客服 FAQ 和项目资料接入模型问答。OpenAI 官方 File Search 文档把它放在 Search and retrieval 工具下，Retrieval 文档说明检索 API 使用 vector stores 作为资料索引。对语雀用户来说，关键不是“能不能上传文件”，而是如何把语雀里的协作文档整理成结构清楚、权限边界明确、检索效果可验证的资料源。

语雀页面本身适合团队编辑，但不一定适合直接进入 AI 检索：标题可能含糊，图片可能依赖外链，文档可能混入草稿、内部评论、过期制度和权限敏感内容。YuqueOut 的价值是先把语雀内容导出到本地，让团队在上传到 OpenAI 之前有机会清洗、分包、审查和留档。

推荐路线：先导出，再入库

最稳的路径可以拆成六步：

1. 用 YuqueOut 批量导出语雀知识库。普通文档优先导出 Markdown，复杂表格或画板按需要另存为 Excel、CSV、HTML、PNG、SVG 等格式。
2. 开启图片本地化。把语雀图片保存到本地 assets/ 目录，避免后续检索结果引用不可访问的外链。
3. 按业务边界清洗。删除草稿、重复文档、过期版本和不应该进入模型的资料。
4. 按应用和权限分包。公开帮助中心、内部流程、客户资料、敏感制度不要混进一个资料包。
5. 上传到 OpenAI vector store。根据官方文档，File Search 和 Retrieval 都围绕 vector stores 组织文件和语义检索。
6. 用真实问题验收。检查答案能否引用正确来源、是否召回旧版本、是否泄露不该出现的资料。

如果你还没有完整导出过语雀知识库，可以先看 语雀知识库批量导出完整教程；如果目标还没有定，可以先读 语雀内容如何整理成 AI 知识库。

Markdown、HTML、PDF 怎么选

OpenAI Retrieval 官方文档列出的支持文件类型包含 .md、.html、.pdf、.txt、.doc、.docx、.json 等格式，并要求文本 MIME 类型使用 utf-8、utf-16 或 ascii 编码。语雀导出时不需要追求单一格式，而要按资料类型选择最容易维护的源文件。

对大多数语雀知识库来说，Markdown 是首选中间格式。它便于 diff、审阅、重命名、拆分、补 FAQ，也便于和 Git 仓库或静态站点一起维护。PDF 可以作为保留排版的补充，但如果只上传 PDF，后续修复标题、段落和权限边界会更麻烦。

导入前清洗语雀资料包

File Search 的检索质量很大程度取决于源文件质量。导入前建议做一次最小但严格的清洗：

• 把“最终版”“备份”“待整理”改成真实标题，例如“退款规则”“企业版开票流程”。
• 删除旧版本、重复会议纪要、临时测试文档和已经废弃的产品说明。
• 在文档开头补一句适用范围，例如“适用于 2026 年企业版售后流程”。
• 把内部黑话补成完整名称，第一次出现时写全称。
• 检查图片路径是否为本地相对路径，不要让关键步骤只存在于不可访问图片里。
• 将客户、财务、人事、法务、未发布产品资料单独放置，默认不进入公开或通用助手索引。

如果资料里有大量图片，可以参考 语雀图片防盗链和本地化处理指南，先把图片依赖降到可控范围。

vector store 应该怎么分

一个常见误区是“一个语雀知识库对应一个 vector store”。实际更合理的边界是应用场景和权限范围。OpenAI Retrieval 文档把 vector stores 描述为资料索引，你可以围绕不同应用建立不同索引，而不是照搬语雀的目录结构。

如果团队已经做过 AI 知识库权限治理，可以沿用 分级、脱敏、分包和验收清单 的边界：公开、内部、敏感资料分开处理。

元数据、文件名和 chunking 检查

OpenAI Retrieval 文档支持给 vector store file 关联 attributes，并可在语义搜索前通过 attribute filtering 缩小范围。对语雀资料来说，建议至少在上传前准备这些可映射到 attributes 或文件名的信息：

• department：资料归属部门，例如 support、product、finance。
• visibility：公开、内部、敏感，不同等级不要混用。
• doc_type：FAQ、SOP、policy、release_note、troubleshooting。
• updated_at：资料最后审阅日期，不只看语雀编辑时间。
• owner：后续谁负责修复未命中问题和过期内容。

文件名也很重要。不要保留 doc-1.md、final.md 这类名称，改成 refund-policy-2026.md、enterprise-invoice-flow.md 这种能反映主题的名字。中文文件名也可以，但要保持稳定、可读、无重复。

关于 chunking，OpenAI Retrieval 文档显示默认会按 token 分块，并提供 chunking_strategy 调整能力。普通 FAQ 和 SOP 通常先用默认设置跑一次验收；如果答案经常只召回半段流程、表格上下文断裂，或者同一篇大文档里混了多个主题，再考虑拆文件或调整 chunking。优先修正文档结构，不要一开始就把所有问题归因于参数。

检索验收问题集

上传完成后，至少准备一组真实问题做验收。每个问题都要记录期望来源、期望答案和失败后的修复动作。

1. 精确命中问题。例如“企业版怎么开票？”检查是否命中正确 SOP。
2. 同义词问题。例如“发票抬头能不能改？”检查模型是否能找到开票规则而不是售后文档。
3. 跨文档问题。例如“退款后发票怎么处理？”检查是否需要同时召回退款和开票文档。
4. 旧版本干扰问题。故意问一个历史流程，确认答案不会引用废弃文档。
5. 图片相关问题。问一个截图教程里的步骤，确认文字说明足够，不能只依赖图片。
6. 权限边界问题。用低权限场景提问敏感信息，确认索引或应用层不会返回不该看的内容。
7. 拒答问题。问资料库里不存在的政策，确认助手会说不知道或请求人工确认。

验收失败时，先回到本地 Markdown 源稿修标题、摘要、FAQ 和文件边界，再重新上传或更新文件。不要只在提示词里要求“回答准确”，因为源资料混乱时提示词很难长期兜底。

隐私、权限和更新策略

YuqueOut 的导出和转换在浏览器本地完成，不会把语雀文档上传到第三方服务器。进入 OpenAI File Search 是导出后的独立动作，团队需要自己确认账号、合规、数据保留、权限和删除策略。OpenAI 官方文档也提供了 vector store 文件删除、批量操作、过期策略等能力说明，实际实现时应以当前控制台和 API 文档为准。

建议每个资料包保留三份记录：原始语雀导出包、清洗后的上传包、上传日志或文件清单。这样当答案出错时，可以快速判断是源文档问题、上传遗漏、分包错误，还是应用层检索范围不对。

如果资料会持续更新，建议按周或按版本重新导出，而不是在语雀和 OpenAI 里手动维护两份不一致的内容。每次更新都要跑同一组验收问题，并记录新增、删除和修改的文件。

常见问题

语雀内容可以直接导入 OpenAI File Search 吗？

不建议直接复制语雀网页。更稳的路径是先用 YuqueOut 导出 Markdown、HTML、PDF 或 TXT 等可解析文件，清洗敏感内容和过期文档，再上传到 OpenAI vector store 供 File Search 检索。

导入 OpenAI File Search 优先选 Markdown 还是 PDF？

多数语雀知识库优先选 Markdown，因为标题、列表、代码块和表格更容易清洗与版本管理。PDF 适合保留版式或合同、手册类资料，但导入后仍要测试检索命中和引用片段。

一个语雀知识库应该对应一个 vector store 吗？

不一定。vector store 的边界应按应用、权限和检索场景决定。公开帮助中心、内部 SOP、客户资料和敏感制度不应混进同一个索引。

YuqueOut 会把语雀文档上传到 OpenAI 吗？

不会。YuqueOut 只负责在浏览器本地导出和转换语雀资料。是否上传到 OpenAI File Search、Dify 或内部 RAG 系统，由用户在导出后自行决定。

OpenAI File Search 导入成功就代表问答可用了么？

不代表。导入成功只说明文件进入索引流程，还需要用真实问题验证召回、引用来源、权限边界、旧版本干扰、图片附件说明和未命中问题的修复路径。