OpenCore文档与知识连接器

File

以 Markdown 格式查看

索引内容

File 连接器把一个或多个文件上传到 OpenCore 管理的存储，并把每个可识别文件索引为文档。它是 load-state 连接器，没有计划刷新，也没有可轮询的源系统。

内容索引行为
文本与文档文件支持的扩展名为 .txt、.md、.mdx、.conf、.log、.json、.csv、.tsv、.xml、.yml、.yaml、.sql、.pdf、.docx、.pptx、.eml、.epub、.html、.xlsx 与 .xlsm。上传 handler 可以存储无法识别的扩展名，但连接器处理时会跳过它们。
表格文件.csv、.tsv、.xlsx 与 .xlsm 会变成 tabular section，并保留已存储 file ID 供 code-interpreter staging 使用。如果 raw-file staging 不可用，表格文件会被跳过。
图片与内嵌图片.png、.jpg、.jpeg 与 .webp 会变成 image section。DOCX 与 PPTX 会主动提取内嵌图片。PDF 只有在部署的 image-extraction-and-analysis 设置启用时才提取内嵌图片。当前 EML、EPUB、HTML、XLSX 与 XLSM 路径不会产生内嵌图片。
ZIP 上传一次上传请求可以展开一个 ZIP。目录以及任一路径部分以 . 开头的条目会被跳过；.onyx_metadata.json 会作为元数据单独存储。第二个 ZIP 会被拒绝。从 archive 提取的文件在索引时仍需通过上面的扩展名检查。

常规管理后台流程接受多个文件，并且浏览器不设置文件扩展名筛选。因此，字节上传成功并不保证连接器会产生已索引文档。

元数据处理时序会影响文档 ID。.onyx_metadata.json 提供的 id 会在选择文档 ID 前处理，因此可以设置文档 ID。首行 inline ONYX_METADATA 在文档 ID 已固定后才提取，所以 inline id 不会替换 ZIP 提供或自动生成的文档 ID。

前置条件

  • 准备使用受支持扩展名的文件，并验证其内容与扩展名匹配。
  • 对加密 PDF，需要注意常规管理后台 File 流程会创建空的内部凭据，且不提供 PDF 密码字段。除非部署另有受支持的摄取路径，否则请使用未加密副本。
  • 对 ZIP 元数据，请在 archive 根目录放置且只放置一个 .onyx_metadata.json，JSON 可以按文件名作为 key，也可以使用每项都包含 filename 的列表。
  • 确保 file store 与 indexing worker 可以保存并处理上传内容。File 上传 handler 不执行连接器专属字节大小限制。当前 MAX_FILE_SIZE_BYTES 索引检查只会在构造出的文档超过配置值时记录日志；不会拒绝上传，也不会跳过该文档。
  • 根据部署环境设置适当的 ingress、storage、memory 与 worker 限制，并在广泛使用前测试有代表性的大 PDF、spreadsheet、图片与 archive。

凭据

方式OpenCore 行为
管理后台 File 上传不需要外部凭据。存储文件并创建 load-state 连接器后，UI 会创建一个空的内部凭据，使 connector-credential pair 具有 owner，并能应用 OpenCore 访问控制。
PDF 密码后端连接器能从凭据读取 pdf_password，但常规管理后台 File 表单不会暴露或填充它。不要假设此 UI 流程支持加密 PDF。

不要把 access token、private key 或源系统凭据作为普通内容上传。File 连接器用于索引内容，不会把文件当作认证凭据使用。

在 OpenCore 中配置

  1. 在管理后台打开连接器，选择 File，并填写易识别的连接器名称。
  2. 选择一个或多个文件。ZIP 默认会被展开；一次上传最多包含一个 ZIP。
  3. 如果需要元数据，请在受支持的纯文本文件首行使用 ONYX_METADATA protocol marker，或在 archive 根目录使用 .onyx_metadata.json。ONYX_METADATA 是 legacy protocol field，不是产品品牌；为保持兼容，必须保留此准确拼写。
#ONYX_METADATA={"title":"示例政策","link":"https://kb.example.com/policies/example","primary_owners":["<OWNER_NAME>"],"department":"People"}
文档正文从这里开始。

会解析的 protocol field 为 id、connector_type、link、file_display_name、title、primary_owners、secondary_owners 与 doc_updated_at。如果需要稳定文档 ID，请把 id 放在 .onyx_metadata.json 中；inline id 解析得太晚，不能更改文档 ID。

ZIP 元数据先应用。对 source type、owner、更新时间、display name、title 与 link，只有非空 inline 值会覆盖已有值，因为连接器使用 fallback（or）选择；空 inline 值不能清除 ZIP 值。Inline 自定义 tag 会更新同名 ZIP 自定义 tag。

自定义 tag 只包含保留排除列表以外的 key。保留字段 document_id、time_updated、doc_updated_at、link、primary_owners、secondary_owners、filename、file_display_name、title、connector_type、pdf_password 与 mime_type 不会进入自定义 tag。document_id 与 time_updated 不是 id 与 doc_updated_at 的解析 alias。在当前兼容 parser 中，id 本身不在自定义 tag 排除列表中，即使 ZIP 级 id 同时也能设置文档 ID。

  1. 受限文件应选择 OpenCore 私有群组。仅当每个 OpenCore 账号都可以搜索连接器中的全部文件时才选择公开。
  2. 创建连接器。UI 会上传文件、创建连接器和内部空凭据、按所选访问范围关联它们，并启动一次索引。
  3. 如需修改现有 File 连接器，请在其管理视图添加或移除文件。必须至少保留一个文件；新增会触发 update indexing，移除会触发 pruning。

权限

文件内容与 ONYX_METADATA owner field 不会创建源 ACL。primary_owners 与 secondary_owners 只是文档元数据。当前管理后台访问选择器不把 File 作为自动同步权限源。

搜索访问仅由连接器的 OpenCore 私有群组或公开模式控制。任何能访问连接器的用户都可以搜索该 File 连接器产生的全部文档。受众不同时，应把文件拆到不同连接器。

文件管理授权与搜索访问相互独立。三个 File 管理端点都先要求 curator 或 admin session。上传在该角色 gate 后执行；列出文件还会检查 connector access；更新文件还会检查 editable access。Global curator 对 Public File 连接器有特殊更新许可，但不能因此更新无关的 Private 连接器。普通 connector 用户不能只因为能够搜索该连接器，就通过这些 Admin endpoint 列出或更新文件。这些管理规则不会创建逐文档搜索权限。

验证

  1. 创建后，确认上传返回已存储文件名，且 indexing attempt 完成。
  2. 搜索同一批次中每种受支持文件类型的独特标题和句子。
  3. 确认用于测试的不受支持扩展名文件不存在，即使上传存储已接受它。
  4. 对 CSV、TSV、XLSX 或 XLSM，检查提取后的表格；如果部署使用 code-interpreter staging，再测试 raw-file analysis。
  5. 对 ZIP，把提取文件名与 archive 对账。确认隐藏路径条目与 .onyx_metadata.json 没有被作为文档索引。
  6. 使用 ZIP 元数据验证 id 会设置文档 ID。再测试一个只含 inline id 的文件：其文档 ID 必须保持自动生成，而当前 parser 可以把 id 保留为自定义 tag。同时验证 title、link、owner metadata、doc_updated_at、一个非保留自定义 tag，以及保留字段没有进入自定义 tag。请使用非敏感值。
  7. 测试每个已分配 OpenCore 群组和一个群组外用户。Metadata owner 不应改变结果。
  8. 在现有连接器中新增一个文件并移除一个文件，然后验证新文档出现，旧文档被 prune。

故障排除

症状检查项
上传成功但没有文档确认文件名使用受支持扩展名、file record 存在，并且 extraction 产生了文本、表格或 image section。上传存储本身不执行索引扩展名 allowlist。
第二个 ZIP 被拒绝这是预期行为。请为该连接器上传使用一个 archive、上传前合并 archive，或使用另一个受支持的 ingestion API。
ZIP 元数据被忽略确认准确的 archive 根文件名是 .onyx_metadata.json、JSON 有效，且每个 key 或 filename 与已存储 basename 匹配。隐藏路径筛选会移除放在 dot-prefixed 目录中的元数据文件。
Inline 元数据出现在可搜索文本中ONYX_METADATA marker 必须位于受支持纯文本文件的第一行并包含有效 JSON。保留准确的 legacy field name。
Inline id 没有改变文档 ID这是预期行为，因为文档 ID 在提取 inline 元数据前已经选定。如果 id 必须设置文档 ID，请把它放在 .onyx_metadata.json 中。当前 parser 仍可能把 inline id 保留为自定义 tag。
document_id、time_updated 或其他保留字段消失保留字段不会进入自定义 tag。document_id 与 time_updated 不是 alias；对应行为请使用 ZIP 级 id 与 doc_updated_at。非空 inline 识别字段可以覆盖已有值，但空值不能清除它们。
大文件上传耗尽资源连接器上传 handler 没有专属字节大小拒绝，且 MAX_FILE_SIZE_BYTES 当前只 warning、不阻断。请执行部署级 request 与 storage 限制、缩小批次，并单独测试 extraction memory。
表格文件被跳过确认已配置 raw-file staging。CSV、TSV、XLSX 与 XLSM 需要 staging callback 才会产生 tabular section。
用户能搜索不属于其源责任范围的文件File 没有源 ACL 同步，metadata owner 也不是授权。请用 OpenCore 私有群组限制连接器，或按受众拆分文件。

相关页面