> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # File > 上传文件用于索引，并明确格式、元数据、大小、更新与访问边界。 ## 索引内容 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**，不是产品品牌；为保持兼容，必须保留此准确拼写。 ```text #ONYX_METADATA={"title":"示例政策","link":"https://kb.example.com/policies/example","primary_owners":[""],"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。 4. 受限文件应选择 OpenCore **私有**群组。仅当每个 OpenCore 账号都可以搜索连接器中的全部文件时才选择**公开**。 5. 创建连接器。UI 会上传文件、创建连接器和内部空凭据、按所选访问范围关联它们，并启动一次索引。 6. 如需修改现有 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 私有群组限制连接器，或按受众拆分文件。 | ## 相关页面 * [连接器与索引](/opencore/knowledge/connectors) * [索引设置](/opencore/knowledge/index-settings)