5.4 · 知识源

知识源

知识源

相关源文件

本章引用的主要源码文件：

• backend/alembic/versions/27fb147a843f_add_timestamps_to_user_table.py
• backend/alembic/versions/d8cdfee5df80_add_skipped_to_userfilestatus.py
• backend/ee/onyx/db/user_group.py
• backend/ee/onyx/server/user_group/api.py
• backend/ee/onyx/server/user_group/models.py
• backend/onyx/db/api_key.py
• backend/onyx/db/auth.py
• backend/onyx/db/document_set.py
• backend/onyx/db/pat.py
• backend/onyx/db/projects.py
• backend/onyx/db/users.py
• backend/onyx/server/features/document_set/api.py
• backend/onyx/server/features/projects/models.py
• backend/onyx/server/features/projects/projects_file_utils.py
• backend/onyx/server/manage/administrative.py
• backend/onyx/server/models.py
• backend/tests/integration/common_utils/managers/user_group.py
• backend/tests/integration/tests/chat/test_chat_document_set_access.py
• backend/tests/integration/tests/projects/test_projects.py
• backend/tests/integration/tests/streaming_endpoints/test_chat_file_attachment.py
• backend/tests/integration/tests/usergroup/test_add_users_to_group.py
• backend/tests/unit/onyx/db/test_delete_user.py
• backend/tests/unit/onyx/db/test_index_attempt_errors.py
• backend/tests/unit/onyx/db/test_projects_upload_task_expiry.py
• backend/tests/unit/onyx/server/test_full_user_snapshot.py
• backend/tests/unit/onyx/server/test_projects_file_utils.py
• backend/tests/unit/onyx/utils/test_vespa_tasks.py
• web/src/app/app/projects/projectsService.ts
• web/src/hooks/useAdminUsers.ts
• web/src/hooks/useUserCounts.ts
• web/src/lib/hooks/useToolOAuthStatus.ts
• web/src/providers/ProjectsContext.tsx
• web/src/refresh-pages/admin/UsersPage/interfaces.ts

本页面详细说明角色（Persona）如何通过文档集（DocumentSet）和项目（Project）访问知识，解释上下文文件处理机制（内存加载与工具中介访问），并记录使用 search_persona_id 和 search_project_id 的搜索过滤系统。

相关页面：助手配置、检索与引用、工具集成

概述

Onyx 中的知识源决定了 AI 助手（角色）在检索过程中可以访问哪些文档。系统提供了以下几种主要机制：

1. 文档集引用：角色通过 Persona.document_sets 关联到精心整理的文档集合 backend/onyx/db/models.py:529-536。
2. 层级节点与附加文档：对特定文件夹、空间或单个文档进行限定范围的搜索 backend/onyx/server/features/persona/models.py:130-133。
3. 用户文件：直接上传文件到角色或项目，通过内存注入或 FileReaderTool 处理 backend/onyx/file_store/utils.py:155-178。
4. 搜索过滤：使用 search_persona_id 或 search_project_id 参数限定向量搜索范围，将结果过滤到相关的知识上下文。

一个关键的优先级规则决定了行为：自定义角色完全取代项目。当自定义角色处于活动状态时，项目文件永远不会被加载或搜索——只有角色自身的 user_files 生效。

角色与文档集关系

数据库模型关系

角色通过 Persona__DocumentSet 关联表链接到文档集。文档集进一步分解为连接器-凭证对（CC Pair），这是入库的基本单元。对这些集合的访问由 _add_user_filters 控制，该函数会检查用户角色和组成员身份 backend/onyx/db/document_set.py:40-88。

知识源实体映射

关键表与类：

来源： backend/onyx/db/models.py:348-580、backend/onyx/server/features/persona/models.py:24-70、backend/onyx/db/document_set.py:40-88

搜索参数确定

搜索过滤与范围限定

系统使用特定的 ID 来限定向量数据库查询的范围。这确保角色只能从其配置的源中检索信息。管理检查（如 validate_object_creation_for_user）确保用户只能链接其有权访问的知识源 backend/ee/onyx/db/user_group.py:137-194。

搜索过滤实现

搜索参数逻辑：

• search_persona_id：当自定义角色具有特定的 user_files 或附加文档时使用。搜索会被过滤，只包含与该角色 ID 关联的文档。
• search_project_id：当用户使用默认角色在"项目"上下文中聊天时使用。
• DISABLE_VECTOR_DB：如果设置了此标志，则在角色创建期间会拒绝 document_sets、hierarchy_nodes 和 attached_documents backend/onyx/server/features/persona/api.py:78-110。

来源： backend/onyx/server/features/persona/api.py:78-110、backend/onyx/db/persona.py:164-186、backend/ee/onyx/db/user_group.py:137-194

上下文文件处理：内存加载与工具中介

用户文件处理

直接上传到助手（用户知识）的文件会根据系统配置和文件大小以不同方式处理。CategorizedFiles 模型跟踪哪些文件是可接受的，哪些应跳过索引 backend/onyx/server/features/projects/projects_file_utils.py:81-87。

知识文件的 Token 预算

categorize_uploaded_files 函数根据 Token 数量和可提取性评估文件是否可接受 backend/onyx/server/features/projects/projects_file_utils.py:161-175。

1. 提取：从 PDF、Docx 和图像（如果启用了视觉功能）中提取文本 backend/onyx/server/features/projects/projects_file_utils.py:16-18。
2. 估算：使用基于补丁的启发式方法（默认 16px 补丁）估算图像 Token backend/onyx/server/features/projects/projects_file_utils.py:115-145。
3. 门控：如果 Token 长度超过配置的阈值，文件会被拒绝，并附带 RejectedFile 原因 backend/onyx/server/features/projects/projects_file_utils.py:76-79。

来源： backend/onyx/server/features/projects/projects_file_utils.py:115-184、backend/onyx/file_store/utils.py:155-178、backend/onyx/db/projects.py:35-50

用户知识与项目

项目知识生命周期

当用户上传文件到项目时，会通过 upload_files_to_user_files_with_indexing 触发以下管线 backend/onyx/db/projects.py:119-126：

1. 分类：categorize_uploaded_files 过滤可接受与拒绝的文件 backend/onyx/db/projects.py:68。
2. 持久化：upload_files 将原始字节存储到文件存储中 backend/onyx/db/projects.py:71。
3. 索引：

• 如果 DISABLE_VECTOR_DB 为 false，则会调度一个 Celery 任务 PROCESS_SINGLE_USER_FILE backend/onyx/db/projects.py:158-168。
• 如果 DISABLE_VECTOR_DB 为 true，则通过本地 drain_processing_loop 处理文件，以实现即时内存可用性 backend/onyx/db/projects.py:149-154。

用户文件存储流程

来源： backend/onyx/db/projects.py:58-116、backend/onyx/db/projects.py:119-176、backend/onyx/server/features/projects/projects_file_utils.py:161-175