> 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 连接器适合把经过审批的文档、表格、PDF 或导出文件直接上传到艾维斯知识库。它没有源系统 ACL 可同步，因此访问边界完全由连接器的公开/私有群组配置决定。

## 适用场景

| 场景     | 建议                                              |
| ------ | ----------------------------------------------- |
| 受控资料包  | 将同一受众可见的文件放在一个连接器中，并绑定对应私有群组。                   |
| 临时项目资料 | 项目结束后移除文件或删除连接器，避免长期留存过期资料。                     |
| 表格分析   | 上传前确认表格文件会被索引，并在需要时验证 code-interpreter staging。 |
| 混合权限文件 | 按受众拆成多个连接器，不要把不同可见范围的文件放在同一批次。                  |

## 索引内容

File 连接器把一个或多个文件上传到艾维斯管理的存储，并把每个可识别文件索引为文档。它是 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。目录以及任一路径部分以 `.` 开头的条目会被跳过。第二个 ZIP 会被拒绝。从 archive 提取的文件在索引时仍需通过上面的扩展名检查。                                                                                                            |

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

## 前置条件

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

## 凭据

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

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

## 在艾维斯中配置

1. 在管理后台打开**连接器**，选择 **File**，并填写易识别的连接器名称。
2. 选择一个或多个文件。ZIP 默认会被展开；一次上传最多包含一个 ZIP。
3. 创建连接器前检查所选文件名，并移除不受支持的格式。上传存储可能接受文件，但 indexing worker 随后仍会跳过它。
4. 受限文件应选择艾维斯**私有**群组。仅当每个 艾维斯账号都可以搜索连接器中的全部文件时才选择**公开**。
5. 创建连接器。UI 会上传文件、创建连接器和内部空凭据、按所选访问范围关联它们，并启动一次索引。
6. 如需修改现有 File 连接器，请在其管理视图添加或移除文件。必须至少保留一个文件；新增会触发 update indexing，移除会触发 pruning。

## 权限

文件内容与描述性 owner metadata 不会创建源 ACL。当前管理后台访问选择器不把 File 作为**自动同步权限**源。

搜索访问仅由连接器的 艾维斯**私有**群组或**公开**模式控制。任何能访问连接器的用户都可以搜索该 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 对账。确认隐藏路径条目没有被作为文档索引。
6. 测试每个已分配 艾维斯群组和一个群组外用户。
7. 在现有连接器中新增一个文件并移除一个文件，然后验证新文档出现，旧文档被 prune。

## 故障排除

| 症状                | 检查项                                                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 上传成功但没有文档         | 确认文件名使用受支持扩展名、file record 存在，并且 extraction 产生了文本、表格或 image section。上传存储本身不执行索引扩展名 allowlist。                               |
| 第二个 ZIP 被拒绝       | 这是预期行为。请为该连接器上传使用一个 archive、上传前合并 archive，或使用另一个受支持的 ingestion API。                                                        |
| 大文件上传耗尽资源         | 连接器上传 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 也不是授权。请用 艾维斯私有群组限制连接器，或按受众拆分文件。                                                             |

## 相关页面

* [连接器与索引](/aivis/knowledge/connectors)
* [索引设置](/aivis/knowledge/index-settings)