RAG 嵌入模型

OneDocs 使用 RAG（Retrieval-Augmented Generation，检索增强生成）辅助文档分析。嵌入模型负责将文档文本转换为向量，使分析流程能够先检索与任务最相关的内容，再将检索结果交给生成模型处理。

本页基于当前提供的产品说明整理。未提供可供核验的仓库源文件，因此涉及具体类名、函数签名、持久化实现、重试策略和内部模块关系的实现细节，不能从源代码确认。

Purpose and Scope

本页说明 OneDocs 中 RAG 嵌入模型的用途、配置方式、可观察状态、基本工作流程、数据边界和常见问题，帮助用户判断何时启用嵌入服务以及如何排查配置问题。

本页不覆盖以下内容：

分析模型本身的 API Key 配置和模型选择；
文档上传、解析和页面识别的完整实现；
生成分析结果的提示词设计；
SiliconFlow 服务端的账户、计费和配额管理；
仓库内部未在现有材料中说明的向量数据库、缓存、索引或后台任务实现。

对于分析模型的配置，请参阅对应的模型配置页面；对于文档解析和上传流程，请参阅对应的文档处理页面。

Overview

RAG 解决的问题

在不使用 RAG 时，分析模型通常需要直接处理整个文档或按顺序处理大量文本。长文档可能导致上下文压力增大，也可能使与当前分析任务相关的段落不容易被优先关注。

启用 RAG 后，系统先把文档内容分块并向量化。分析请求到达后，系统根据任务语义检索相关文本块，再把这些文本与分析提示组合起来交给 AI 模型。这样做的目标是：

让模型更容易定位与任务相关的章节和段落；
减少长文档中无关内容对上下文的占用；
提高对文档结构和语义关系的覆盖能力；
在文档较长时，以检索结果作为分析前的内容筛选步骤。

嵌入模型的职责

嵌入模型并不直接生成最终分析结果。它的职责是将文本转换为可用于相似度检索的向量表示。当前产品说明指定使用 SiliconFlow 提供的 BAAI/bge-m3 模型进行文本嵌入。

分析模型与嵌入模型是两个独立的配置边界：嵌入请求使用 SiliconFlow Token，分析请求使用分析模型对应的 API Key。两者的额度和可用性不应混为一谈。

配置入口与配置流程

获取 SiliconFlow Token

当前说明中的配置流程如下：

访问 SiliconFlow 并注册账号；
在控制台获取 API Token；
确认账户拥有可用额度；
返回 OneDocs，在通用设置中填写 Token。

产品说明指出，BAAI/bge-m3 可使用注册赠送的免费额度，但免费额度属于 SiliconFlow 账户侧的资源，具体剩余量和可用条件应以 SiliconFlow 控制台为准。

在 OneDocs 中填写 Token

配置入口位于：

设置 → 通用 → 🧠 RAG 嵌入模型配置

在输入框中填入 SiliconFlow API Token 后，应观察页面显示的状态指示。现有说明定义了两类主要状态：

状态	含义	建议操作
绿色	嵌入服务可用	可以继续使用启用 RAG 的分析流程
黄色	嵌入服务不可用	检查 Token、网络连接以及 SiliconFlow 额度

配置成功后，页面可能显示以下两种文案之一：

✅ 已配置个人 Token，嵌入服务可用：表示使用了用户自己的 Token；
✅ 使用开发者提供的免费额度，剩余次数：XX：表示使用开发者提供的免费额度，并展示剩余次数。

现有材料没有说明 Token 的本地存储方式、是否加密、是否支持环境变量覆盖或是否会在重新打开页面后自动恢复。因此这些行为不能在本页中进一步推断。

工作流程

RAG 的逻辑流程可以概括为以下几个阶段：

文本分块：把文档拆分为较小的文本块，说明中称其依据页面顺序、段落和语义进行切分；
嵌入向量化：将文本块发送给 BAAI/bge-m3，获得对应向量；
向量存储：保存文本块及其向量，以便后续分析请求检索；
相关内容检索：分析任务到来后，使用任务内容查找相关文本块；
提示词组合：将检索到的文本块与分析任务提示词组合；
生成分析结果：把组合后的上下文发送给 AI 分析模型。

当前材料只描述了该流程的产品级行为，没有给出向量存储类型、相似度算法、Top-K 默认值、分块大小、重叠长度、索引生命周期或检索失败时的具体内部实现。

配置成功时的分析路径

当嵌入服务可用时，预期路径是：文档内容先完成分块和向量化，分析请求再通过向量检索缩小输入范围。启用 RAG 的价值主要体现在长文档或需要定位分散信息的分析任务上。

未配置或不可用时的回退路径

产品说明明确指出，即使不配置嵌入 Token，仍然可以使用基本分析功能。此时 OneDocs 使用全量分块策略，按页面顺序逐块分析，而不是通过嵌入向量检索相关内容。

这意味着嵌入服务不是基本分析功能的硬性前置条件，而是用于改善长文档分析质量和检索效率的增强能力。回退策略的代价是：对于长文档，模型可能需要处理更多按顺序提供的内容，分析质量可能低于启用 RAG 的情况。

数据流与隐私边界

启用嵌入功能时，文档文本会通过 SiliconFlow API 发送到 SiliconFlow 服务器进行向量化。当前说明同时指出：OneDocs 不会存储或转发文档内容到其他服务器。

因此，使用者在启用该功能前应区分两个事实：

OneDocs 的产品行为声明不代表文本不会离开本地环境；嵌入请求本身会将文本发送给 SiliconFlow；
OneDocs 与 SiliconFlow 的数据处理边界不同，账户、配额、服务端日志和保留策略应以 SiliconFlow 的政策为准。

对包含敏感、受监管或不允许发送到第三方服务的内容，是否启用 RAG 应由组织的数据合规要求决定。现有材料没有说明脱敏、字段过滤、传输加密配置或数据保留控制，因此不能声称系统提供这些能力。

配置选项

选项	类型	默认值	说明
SiliconFlow API Token	字符串	未说明	用于调用 SiliconFlow 的嵌入服务。配置入口为“设置 → 通用 → RAG 嵌入模型配置”。
嵌入模型	模型标识	`BAAI/bge-m3`	当前产品说明指定的文本嵌入模型。是否可由用户修改，现有材料未说明。
RAG 启用状态	服务状态	未说明	由页面状态指示反映嵌入服务是否可用。

未在现有材料中发现以下可配置项：分块大小、分块重叠、检索数量、相似度阈值、向量数据库地址、请求超时、重试次数和批处理大小。它们可能由系统固定，也可能存在于未提供的实现代码中；不能据此假定默认值。

运行状态与排查

绿色状态

绿色状态表示当前嵌入服务可用。可以继续执行需要 RAG 的分析操作。如果分析结果仍不符合预期，应优先检查文档解析质量、文本分块效果以及分析模型配置；仅凭嵌入服务绿色状态，不能保证最终分析结果一定正确。

黄色状态

黄色状态表示嵌入服务不可用。建议按以下顺序排查：

重新确认 Token 是否完整、有效且没有多余空格；
确认 Token 属于 SiliconFlow，而不是分析模型服务商；
确认 SiliconFlow 账户仍有可用额度或剩余次数；
检查当前网络是否能够访问 SiliconFlow API；
重新保存配置并观察状态指示是否变化；
如果服务仍不可用，先使用不依赖嵌入服务的基本分析流程。

如果页面没有显示更具体的错误信息，现有材料无法进一步判断是认证失败、配额耗尽、网络错误、服务端错误还是请求格式错误。

API 与实现边界

当前提供的资料只描述了产品配置和行为，没有提供仓库源代码、HTTP 路由、服务接口、函数签名或异常类型。因此：

没有可准确引用的内部 API 方法；
没有可确认的请求和响应字段；
没有可确认的错误码映射；
没有可确认的同步/异步调用方式；
没有可确认的重试、超时和并发控制策略。

实现细节 not found in source material。若需要维护或扩展该能力，应先核验嵌入服务调用封装、配置模型、状态探测逻辑、分块器、向量存储适配器和分析流程调用点，再补充 API 级文档。

性能、可用性与一致性注意事项

从产品行为可以确认，RAG 的主要收益场景是长文档：通过检索相关文本块，减少分析时处理全部内容的需要。与此同时，嵌入阶段会增加一次外部服务依赖，因此可用性取决于 SiliconFlow Token、账户额度和网络连接。

现有材料没有提供性能基准，因此不能给出以下数值或保证：

单页或单文档嵌入耗时；
向量检索延迟；
最大文档大小；
并发分析数量；
SiliconFlow 请求限流行为；
失败请求是否自动重试；
文档修改后向量是否增量更新。

在运营层面，建议把“嵌入服务可用”与“分析结果质量”分别观察：前者是外部嵌入依赖的健康状态，后者还受到分块、检索、提示词和分析模型的共同影响。

常见问题

不配置嵌入模型能使用吗？

可以。OneDocs 会使用全量分块策略，按页面顺序逐块分析，基本分析仍可进行。但对长文档而言，分析质量可能不如启用 RAG 时稳定。

嵌入模型会消耗分析模型 API Key 的额度吗？

不会。嵌入模型使用独立的 SiliconFlow Token，分析模型 API Key 与嵌入 Token 是分开的配置和额度边界。

免费额度用完后怎么办？

可以选择注册新的 SiliconFlow 账号获取额度、为 SiliconFlow 账户充值，或不使用嵌入功能并继续使用基本分析。实际可用方案取决于账户政策和组织合规要求。

嵌入数据会上传到服务器吗？

会。文档文本会通过 SiliconFlow API 发送到 SiliconFlow 服务器进行向量化。产品说明同时声明 OneDocs 不会存储或转发文档内容到其他服务器，但第三方服务侧的数据处理应以其官方政策为准。

为什么嵌入服务可用但分析结果仍不理想？

嵌入服务只负责文本向量化和检索辅助，不负责最终答案生成。结果还可能受到文档解析、文本分块、检索相关性、分析提示词和生成模型能力影响。当前材料没有提供足够的诊断信息来确定具体原因。

扩展点与待核验事项

若后续需要将本页扩展为面向开发者的实现参考，至少需要从源代码核验以下内容：

Token 的配置模型、保存位置和敏感信息保护方式；
SiliconFlow 客户端的请求地址、认证头和请求体；
BAAI/bge-m3 模型标识是否固定；
分块策略及其边界处理；
向量存储和索引生命周期；
检索排序、Top-K 和阈值；
外部调用的超时、重试、限流和错误转换；
文档更新或删除时的向量一致性；
多用户或并发分析时的 Token、配额和数据隔离；
状态指示灯的探测时机和健康检查条件；
自动化测试对成功、回退和失败路径的覆盖。

在这些信息可获得前，不应把上述项目描述为现有系统已经提供的能力。

SiliconFlow：获取嵌入服务 Token 的产品说明入口。
分析模型配置：用于配置生成分析结果所使用的模型及其 API Key。
文档上传与解析：用于了解文档如何进入分块和分析流程。