# 资料库
资料库将[云盘](/apps/storage)中指定目录的文件抽取为可检索的段落。你可以按关键词或语义查找内容，打开原文查看页码与章节。在对话时，[助手](/agent/overview)也可以引用这些段落回答问题。你在云盘中能读到哪些文件，就能在资料库中搜索到哪些文件。
## 谁能用
资料库的读取权限与[云盘](/apps/storage)完全一致。读取资料库不需要单独的资料库权限点。
| 权限 / 角色 | 默认谁有 | 能做什么 |
|---|---|---|
| 任意登录成员（无需资料库权限点） | 全体登录成员 | 查看概览与文件列表、在阅读器中阅读抽取文本、检索段落、下载原文件（仅限在云盘中有权读取的文件） |
| 云盘「上传与新建」 | 在资料目录拥有该云盘权限的成员 | 在主页点击「上传资料」或拖拽文件上传到资料目录 |
| 单文件读取权限 | 在云盘中能读取该文件的成员 | 对单份文件执行「重新索引」 |
| 「管理资料库」 | 组织管理员（未自管角色时） | 「指定资料目录」、「更换目录」、「全部重新索引」 |
权限控制特性：
- **可见范围受限**：可见文件集合为资料目录子树中你在云盘有权读取的文件。你在云盘中读不到的文件，在资料库中均视为不存在。
- **管理权限隔离**：组织未自管角色时，「管理资料库」权限默认仅管理员拥有。若未获得该权限，未指定目录时界面显示「请管理员先指定资料目录。」；若尝试执行管理操作，系统提示「你的角色没有「管理资料库」权限：指定资料目录和重新索引全部文件需要它」。
- **助手写操作保护**：[助手](/agent/overview)执行写操作时不会直接执行，必须生成[草稿](/agent/drafts)或等待你[确认](/agent/confirm)。
## 怎么打开
1. 在[工作台](/guide/workspace)进入「知识与文件」套件，点击「资料库」标签。在套件中本应用为可选应用。当需要让云盘里的制度、手册、合同等文件内容可被搜索并被助手引用时安装，需要搭配[云盘](/apps/storage)使用。未安装云盘时功能不完整。
2. 在浏览器中直接输入地址访问：`https://library.apps.{你的域名}/`。
顶栏导航：
- 「资料」：进入资料库主页列表。
- 「检索」：进入内容检索页。
> **提示**
>
> 应用没有工作台多入口。在手机或窄屏设备上访问时，系统支持同一套列表与检索功能，表格会自动切换为卡片式展示。打开某份资料后，可以从结果或目录定位到具体段落。点「在云盘中打开」会跳到云盘里的原文件。
## 界面一览
资料库主要由主页「资料」、阅读器与「检索」页构成：
图：「资料库」主页
1. 页头「资料库」
2. 「上传资料」：文件会放进指定的云盘目录
3. 统计：「文件」「已索引」「排队 / 解析中」
4. 按文件名筛选
5. 资料文件列表：名字、状态、段落
| 页面 / 区域 | 主要内容与功能 |
|---|---|
| 主页页头 | 显示标题「资料库」；组织未配置嵌入模型时，显示提示「未配置嵌入模型，仅支持关键词检索。」；右侧提供「在云盘中打开」「全部重新索引」「上传资料」按钮（指定目录后展示，后两项需对应权限）。 |
| 统计卡片区 | 展示四项统计数据：
1. 「文件」：资料目录下的文件总数；
2. 「已索引」：已完成索引的文件数，说明提示包含的总段落数（若存在部分向量化文件，追加提示部分向量化的文件数）；
3. 「排队 / 解析中」：正在排队或解析的文件数；
4. 「失败 / 无文字」：解析失败或无文字的文件数。 |
| 目录状态栏 | 1. 未指定目录：展示提示「还没有指定资料目录」。管理员显示「选一个云盘目录作为资料目录。」与「指定资料目录」按钮；普通成员显示「请管理员先指定资料目录。」；
2. 已指定目录：表头展示当前云盘目录路径，拥有管理权限时显示「更换目录」按钮。 |
| 列表筛选栏 | 提供文件名搜索框（占位符「文件名」，无障碍标签「按名字查找文件」，最多 80 个字）；状态下拉菜单（「全部状态」及各状态）；类型下拉菜单（「全部类型」及「PDF」「Word」「Markdown」「文本」「表格 CSV」「网页」「其他」）。 |
| 文件列表表格 | 列包含「名字」「状态」「大小」「段落」「更新」「操作」。文件超出向量化上限时带有「部分向量化」徽标（悬停提示「超出向量化上限的段落只参与关键词检索」）。行操作菜单提供「阅读」「在云盘中打开」「下载原文件」「重新索引」。窄屏下以卡片呈现。 |
| 列表页脚 | 显示已加载的文件数量（若有下一页追加「，还有更多」），以及「加载更多」按钮。 |
| 阅读器 | 顶栏提供返回链接「← 资料库」，以及「在云盘中打开」「下载原文件」「重新索引」操作；展示资料页数、段落数与解析时间；提供「目录」导航；正文支持点击「加载前面的内容」「加载后面的内容（还有 」...「 段）」分段阅读；每段标注页码（如第 x 页或跨页第 x–y 页）。 |
| 「检索」 | 标题为「检索」；提供检索输入框（占位符「输入问题或关键词，例如：出差住宿标准是多少」，无障碍标签「检索问题」，最多 300 个字）与「检索」按钮；单选支持「混合」「关键词」「语义」三种模式；结果展示找到的段落数量，结果卡片显示命中方式徽标与「相似度」分数，点击可打开原文并定位到段落。 |
## 常用操作
### 指定资料目录（管理员）
图：「更换资料目录」对话框
1. 已指定目录后，对话框标题是「更换资料目录」
2. 「指定方式」：新建目录，或选用云盘里已有的
3. 「新建资料目录」：建在组织共享里
4. 「选择云盘里已有的目录」：已有文件会开始解析
5. 「目录名称」：最多 80 个字
6. 「取消」；提交按钮在未指定时是「指定」，已指定时是「更换」
1. 在左侧导航或工作台进入「资料库」。
2. 在未指定目录提示区域，点「指定资料目录」。
3. 填写指定目录表单：
| 字段 | 必填 | 说明 |
|---|---|---|
| 「指定方式」 | 是 | 单选「新建资料目录」（在云盘的「组织共享」空间里建一个目录）或「选择云盘里已有的目录」（已有文件会开始解析） |
| 「目录名称」 | 是（新建时） | 资料目录名称，默认值为「资料库」，最多 80 个字，不能包含 `/` 或 `\` |
| 「云盘目录」 | 是（选择已有目录时） | 在下拉列表中选择云盘已有目录（占位符「选择目录」） |
4. 点「指定」。系统提示「已指定资料目录，目录里的文件会陆续被解析」，目录内的文件开始排队解析。
**异常提示说明**
若选择已有目录时云盘中没有可用目录，系统提示「没有可管理的目录，请先在云盘新建。」；若读取目录列表失败，系统提示「没能读到目录列表」，可点「重试」；未选择目录直接提交时提示「请选一个目录」。输入名称不符合要求时，系统分别提示「名称不能为空」「名称最多 80 个字」或「名称里不能有 / 或 \\」。
### 上传资料文件
1. 在主页右上角点「上传资料」，或直接将本地文件拖入列表区域。
2. 拖入文件时，界面提示「松开即可上传」，并显示放进资料目录与目标目录名。
3. 系统显示进度「正在上传……」。
4. 上传完成后，系统弹出上传结果提示：
- 单个文件成功：提示「已上传……，稍后会出现在列表里并开始解析」。
- 多个文件全部成功：提示「已上传……个文件，稍后会开始解析」。
- 部分文件失败：提示「已上传……个，……个没有成功，如……」。
> **注意**
>
> 单文件大小上限为 50 MB（与[云盘](/apps/storage)一致）。如果上一批文件尚未传完，再次上传时系统会提示「上一批文件还在上传，请稍等」。如果手动取消则提示「已取消」，网络或服务端异常时提示「上传失败」。
> 支持上传的文件格式包括：PDF、Word（docx）、Markdown、文本、表格 CSV、网页。
### 检索段落
图：资料库「检索」页
1. 「检索」页
2. 检索框：问题或关键词
3. 「混合」：关键词加语义（默认）
4. 「关键词」：只找包含这些词的段落
5. 「语义」：按意思找（要嵌入模型）
1. 在顶栏点「检索」。
2. 在检索输入框中输入问题或关键词（最多输入 300 个字）。
3. 选择检索方式：
| 方式 | 说明 | 适用场景 |
|---|---|---|
| 「混合」 | 「关键词加语义，默认推荐」 | 结合关键词精准匹配与向量语义相关度，适合绝大多数搜索 |
| 「关键词」 | 「只找包含这些词的段落」 | 精确匹配原文字词，适合查找专有名词、编号或术语 |
| 「语义」 | 「按意思找」 | 理解自然语言问题意图，适合用口语化问题寻找解答 |
4. 点「检索」。
5. 查看检索结果：系统显示找到的段落数量，每条卡片标有「相似度」与匹配分数，以及「关键词」「语义」或「关键词 + 语义」命中徽标。
6. 点选目标卡片（卡片无障碍提示打开对应标题并定位到该段落）。系统打开阅读器并定位到对应段落。
> **提示**
>
> 未输入内容时，页面提示「问一个问题」与「点结果打开原文。」。若没有找到匹配内容，系统提示「没有找到相关段落」以及「换个关键词；刚上传的文件需等到「已索引」，扫描件无法检索。」。若组织未配置嵌入模型，页面显示提示「未配置嵌入模型，仅支持关键词检索。」，「语义」和「混合」中的语义部分不可用。
### 阅读抽取文本
1. 在主页列表中点击文件名，或在行操作菜单点「阅读」。
2. 系统进入阅读器页面。
3. 查看文件抽取内容，顶部展示资料页数、段落数与解析时间。
4. 浏览目录导航（无障碍标签为「目录」），正文按段落呈现并标有页码（如第 x 页或跨页第 x–y 页）。
5. 点「加载前面的内容」或点加载后续内容按钮（显示还有多少段）按需加载相邻段落。
6. 若需查看原始文件，点顶栏「在云盘中打开」或点「下载原文件」。
7. 若需返回列表，点左上角「← 资料库」。
**异常与限制提示**
- 若文件仍在解析，界面显示「排队等待解析。」或「正在抽取文字并建立索引。」，附带状态名称与「原因：」详情。
- 若文件无内容，界面显示「没有可显示的内容」。
- 若文件已被移出目录或无权限，界面显示「找不到这份资料」与「可能已移出资料目录，或你无权查看。」。
- 若超出向量化上限，界面提示「部分段落未向量化，仅支持关键词检索。」。
- 若抽取文本超过约 2 MB，界面提示「文本过长，仅抽取了前面部分。」。
### 重新索引单份文件
1. 在文件列表行操作菜单或阅读器顶栏点「重新索引」。
2. 文件的错误计数清零，状态重新进入「排队中」。
3. 系统重新抽取文本并重新建立索引。
### 全部重新索引（管理员）
1. 在主页右上角点「全部重新索引」。
2. 系统弹出确认弹窗「全部重新索引？」，提示：「资料目录里的所有文件都会重新解析，期间检索结果可能暂时不全；使用嵌入模型时会产生用量。」。
3. 点确认。系统提示「已安排全部重新索引，状态会陆续更新」，所有文件重新排队解析。
### 更换资料目录（管理员）
1. 在主页目录路径旁点「更换目录」。
2. 系统弹出「更换资料目录」对话框，显示说明「目录（含子目录）里的文件会被索引，权限与云盘一致。」。
3. 选择「新建资料目录」或「选择云盘里已有的目录」，确认名称或选择新目录。
4. 点「更换」。系统提示「已指定资料目录，目录里的文件会陆续被解析」。
> **注意**
>
> 更换资料目录后，原目录中的文件将不再属于资料库，原有的索引和向量数据会被清除。
### 在云盘中维护文件
资料库的文件生命周期直接跟随[云盘](/apps/storage)：
- **移出目录或删除**：在云盘中将文件移出资料目录，或将文件移入回收站软删除，资料库中的对应条目与向量会被立即清除。
- **上传新版本**：在云盘中上传文件的新版本后，新版本文件首先回到「排队中」状态；旧版本的段落保留供检索，直到新版本索引成功替换；若新版本解析失败，旧版本段落依然保留可搜。
## 状态说明
文件的解析与索引生命周期流转如下：
```
排队中 → 解析中 → 已索引 | 无可抽取文本 | 不支持 | 失败
```
流转规则：
- 新上传文件或文件上传新版本时，首先进入「排队中」。
- 解析过程中遇到临时错误会自动退避重试，多次重试仍失败后状态转为「失败」。
- 点击「重新索引」会清零失败重试次数，重新从「排队中」开始流转。
- 上传新版本时，旧版本的段落会一直保留供检索，直到新版本成功生成新索引；如果新版本解析失败，旧段落依然可被检索。
| 状态名称 | 界面提示文案 | 说明与处理建议 |
|---|---|---|
| 「排队中」 | 「等待解析。」 | 文件已进入解析队列，等待后台服务抽取文本与建立索引。 |
| 「解析中」 | 「正在抽取文字并建立索引。」 | 后台服务正在读取文件内容、切分段落并生成向量数据。 |
| 「已索引」 | 「可检索。」 | 文本抽取和向量化成功，文件段落已可被全文检索和语义检索。 |
| 「无可抽取文本」 | 「扫描件或图片 PDF 暂不支持 OCR，请上传带文字层的版本。」 | 文件内没有识别出文字图层（例如扫描件或纯图片 PDF）。目前系统不支持 OCR，请上传包含文本层的版本。 |
| 「不支持」 | 「暂不支持这种格式。」 | 系统暂不支持该文件格式的抽取解析（如表格 xlsx、幻灯片 pptx、旧版 doc 文件、压缩包）。 |
| 「失败」 | 「解析出错，请联系管理员重新索引。」 | 文件解析过程中发生错误。多次重试失败后停留在该状态。可联系管理员或手动点「重新索引」。 |
| 「未知」 | 原文或显示「未知」 | 遇到了未定义或无法识别的状态代码。 |
特殊说明与徽标：
- **「部分向量化」徽标**：每份文件最多对前约 400 段生成语义向量索引。超出部分不参与语义向量化，仅参与关键词检索。列表显示「部分向量化」徽标（悬停提示「超出向量化上限的段落只参与关键词检索」），状态说明附加「部分已向量化：超出的段落只参与关键词检索」。
- **「文本过长，已截断」**：单份文件抽取文本超过约 2 MB 时，文本会被截断，超出部分不再抽取。列表或阅读器提示「文本过长，已截断」或「文本过长，仅抽取了前面部分。」。
## 让助手帮你做
你可以通过[助手](/agent/overview)用自然语言管理资料库或检索知识内容。平台检索时，助手会引用资料库中的段落与页码回答问题。
你可以对助手说：
> 把组织共享里的制度文件夹指定为资料目录
> 把这份员工手册重新索引
> 资料库全部重新索引
> 出差住宿标准是多少
**说明**
- **权限与确认机制**：助手执行管理操作时必须通过[草稿](/agent/drafts)或等待你[确认](/agent/confirm)：
- 指定资料目录：助手起草操作，需要你确认：「确认后，这个文件夹（含子文件夹）里的所有文件都会被读取并可被搜索（包括助手的检索，仍按每个人在云盘里的权限）；换掉原来的目录后，原目录的文件不再属于资料库。」
- 重新索引全部：助手执行前需要你确认：「资料库里的全部文件都会重新排队解析，文件很多时要花一些时间；内容没变的文件不会重复产生向量费用。」
- 单文件重新索引：助手可直接执行动作。
- **助手权限隔离**：助手无法绕过你在[云盘](/apps/storage)中的文件权限。你只能检索和引用你在云盘中有权读取的文件。
- **能力边界**：助手不能绕过权限读取文件，也不能直接上传文件（上传须由你在页面完成）。
## 设置
资料库没有独立的设置页面。所有管理操作均集中在主页：
- **目录设置**：在主页执行「指定资料目录」或「更换目录」。
- **索引刷新**：在主页执行「全部重新索引」。
- **模型配置**：嵌入模型由组织级模型配置决定，资料库内不提供独立模型开关。当组织未配置嵌入模型时，界面显示只读提示「未配置嵌入模型，仅支持关键词检索。」。
## 注意事项
- **目录数量上限**：每个组织只能指定 1 个资料目录。
- **文件规模限制**：索引子树与检索可见集合各最多约 20 000 个文件。超出规模时，概览与检索区域会附带说明。
- **文件大小与文本上限**：
- 单文件读取大小上限为 50 MB（与[云盘](/apps/storage)相同）。
- 单文件抽取文本大小超过约 2 MB 时会被截断。
- 单文件向量化上限约为前 400 段，超出段落只参与关键词检索。
- **权限严格跟随云盘**：资料库本身不维护独立的用户阅读权限，完全以[云盘](/apps/storage)的权限与可见性为准。一旦云盘中的共享范围或数据权限发生变动，资料库中的可见性立即同步更新。
- **回收站与清理机制**：资料库没有独立的回收站。在云盘中将文件软删除移入回收站后，资料库中该文件的索引条目与向量数据会被同步删除。
- **不支持格式限制**：扫描件与图片 PDF 无法抽取文字（标记为「无可抽取文本」）；xlsx、pptx、旧版 doc 文件与压缩包无法解析（标记为「不支持」）。
## 目前不支持
- OCR 文字识别（扫描件和纯图片 PDF 无法抽取文字）。
- 音视频转写。
- 表格 xlsx、幻灯片 pptx、旧版 doc 文件及压缩包格式解析。
- 同时指定多个资料目录（每个组织仅支持 1 个资料目录）。
- 检索结果重排序。
- 跨语言检索。
- 阅读器「被引用」面板。
## 常见问题
### 为什么我在资料库中搜不到同事能搜到的某份文件？
资料库的可见性完全以[云盘](/apps/storage)为准。你在云盘中能读到哪些文件，才能在资料库中看到和搜到哪些文件。如果你在云盘中对该文件没有读取权限，该文件在资料库中对你而言相当于不存在。请联系文件管理者在云盘中为你开通读取权限。
### 为什么上传的 PDF 文件状态显示为「无可抽取文本」？
资料库目前不支持 OCR 文字识别功能。如果上传的 PDF 文件是纯图片扫描件，或者没有可抽取的文字图层，系统无法从中抽取正文段落。请重新导出并上传包含文本图层的 PDF 文件。
### 列表里的「部分向量化」徽标是什么意思？
每份文件通常最多为前约 400 段生成向量数据。当文件的段落数量超出该上限时，系统会对超出部分标记为「部分向量化」。超出的段落不会参与语义向量检索，但仍然支持关键词检索。
### 为什么检索页面提示「未配置嵌入模型，仅支持关键词检索。」？
语义检索和混合检索依赖组织配置的文本嵌入模型。如果组织尚未配置嵌入模型，资料库会自动降级为关键词检索，「语义」检索模式以及「混合」模式中的语义部分将无法使用。需由管理员在组织模型设置中配置嵌入模型后方可启用。
### 执行「全部重新索引」会产生额外的模型用量费用吗？
对所有文件执行重新索引时，内容未发生变动的文件不会重复产生向量费用。仅内容有变动或需要新生成向量的文件在使用嵌入模型时会产生相应模型用量。