关键概念与术语
关键概念与术语
相关源文件
以下文件为本维基页面的生成提供了上下文：
backend/alembic/versions/74379b447d4c_add_paste_as_tile_to_user.pybackend/onyx/auth/schemas.pybackend/onyx/auth/users.pybackend/onyx/connectors/factory.pybackend/onyx/db/enums.pybackend/onyx/db/models.pybackend/onyx/db/user_preferences.pybackend/onyx/server/manage/get_state.pybackend/onyx/server/manage/models.pybackend/onyx/server/manage/users.pybackend/tests/api/test_api.pybackend/tests/unit/onyx/auth/test_single_tenant_jwt_strategy.pybackend/tests/unit/onyx/server/test_upload_files.pydeployment/aws_ecs_fargate/cloudformation/services/onyx_nginx_service_template.yamldeployment/aws_ecs_fargate/cloudformation/services/onyx_web_server_service_template.yaml- [web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx](web/src/app/admin/connectors/[connector]/AddConnectorPage.tsx)
- [web/src/app/admin/connectors/[connector]/pages/Advanced.tsx](web/src/app/admin/connectors/[connector]/pages/Advanced.tsx)
- [web/src/app/admin/connectors/[connector]/pages/ConnectorInput/FileInput.tsx](web/src/app/admin/connectors/[connector]/pages/ConnectorInput/FileInput.tsx)
- [web/src/app/admin/connectors/[connector]/pages/DynamicConnectorCreationForm.tsx](web/src/app/admin/connectors/[connector]/pages/DynamicConnectorCreationForm.tsx)
- [web/src/app/admin/connectors/[connector]/pages/utils/google_site.ts](web/src/app/admin/connectors/[connector]/pages/utils/google_site.ts)
web/src/app/admin/indexing/status/CCPairIndexingStatusTable.tsxweb/src/app/admin/layout.tsxweb/src/components/admin/connectors/AccessTypeForm.tsxweb/src/components/admin/connectors/AccessTypeGroupSelector.tsxweb/src/components/icons/icons.tsxweb/src/hooks/useTokenRefresh.test.tsxweb/src/hooks/useTokenRefresh.tsweb/src/lib/connectors/connectors.tsxweb/src/lib/connectors/credentials.tsweb/src/lib/sources.tsweb/src/lib/types.tsweb/src/providers/UserProvider.tsx
目的与范围
本文档定义了 Onyx 代码库中使用的核心数据模型概念和术语。它涵盖了数据入库、知识检索、AI 配置和用户交互中涉及的主要实体。本页面作为自然语言系统描述与实现这些描述的具体代码实体（类、模型和接口）之间的技术桥梁。
检索增强生成（RAG）
Onyx 将检索增强生成（RAG）作为其核心的知识驱动聊天模式。RAG 将文档检索与大语言模型（LLM）生成相结合，以生成有具体来源支持的答案。
RAG 流程与代码实体
来源： backend/onyx/db/models.py:547-641, backend/onyx/llm/override_models.py:99-100
数据源与连接器
ValidSources 枚举
ValidSources 枚举定义了所有支持的数据源类型。前端的 SOURCE_METADATA_MAP 作为图标、显示名称和类别的真实来源。
来源： web/src/lib/types.ts:2-3, web/src/lib/sources.ts:92-416, backend/onyx/configs/constants.py:50-50
连接器实体
Connector 表示数据源的配置。它定义了*要索引什么*（例如，特定的 GitHub 仓库或网站 URL）。
| 字段 | 类型 | 描述 |
|---|---|---|
id | 整数 | 主键 |
source | DocumentSource | 来自 ValidSources 枚举的类型 backend/onyx/configs/constants.py:50 |
input_type | InputType | LOAD_STATE、POLL 或 EVENT backend/onyx/connectors/models.py:58 |
connector_specific_config | JSON | 配置，如 base_url 或 repo_owner |
refresh_freq | 整数 | 索引运行之间的秒数 |
来源： backend/onyx/db/models.py:410-443, web/src/lib/connectors/connectors.tsx:145-248
凭证与 CC 对
凭证实体
Credential 存储加密的认证数据。凭证可以在多个连接器之间共享。加密通过 EncryptedString 和 EncryptedJson 处理，这些类将值包装在 SensitiveValue 对象中。
| 字段 | 类型 | 描述 |
|---|---|---|
id | 整数 | 主键 |
credential_json | EncryptedJson | 加密的令牌、API 密钥或证书 backend/onyx/db/models.py:122-135 |
user_id | UUID | 凭证的所有者 |
source | DocumentSource | 关联的源类型 |
来源： backend/onyx/db/models.py:254-298, web/src/lib/connectors/credentials.ts:40-46
连接器凭证对（CC 对）
CC 对是索引的核心单元。它将 Connector（配置）与 Credential（认证）关联起来。
来源： backend/onyx/db/models.py:445-545, web/src/app/admin/connector/[ccPairId]/types.ts:34-34, backend/onyx/db/enums.py:180-186
角色（AI 助手）
角色（在用户界面中称为助手）是一个配置好的 AI 实体，具有特定的系统提示词、一组工具以及关联的知识边界。
| 字段 | 类型 | 描述 |
|---|---|---|
name | 字符串 | 助手的显示名称 |
system_prompt | 字符串 | 大语言模型（LLM）的核心指令 |
tools | 关系 | 角色可以使用的工具列表 backend/onyx/db/models.py:734-738 |
document_sets | 关系 | 助手的知识边界（DocumentSets） |
llm_model_version_override | 字符串 | 特定模型（例如 gpt-4o） |
llm_model_provider_override | 字符串 | 特定提供商（例如 OpenAI） |
来源： backend/onyx/db/models.py:680-840, web/src/lib/types.ts:1-1, backend/onyx/llm/override_models.py:98-99
用户角色与组
Onyx 使用分层角色系统和基于组的访问控制（RBAC）。
UserRole 枚举
| 角色 | 描述 |
|---|---|
ADMIN | 完全系统访问权限 web/src/lib/types.ts:68 |
GLOBAL_CURATOR | 对所有所属组执行管理员操作 web/src/lib/types.ts:70 |
CURATOR | 管理特定组及其连接器 web/src/lib/types.ts:69 |
BASIC | 标准搜索和聊天访问权限 web/src/lib/types.ts:67 |
LIMITED | 受限访问权限，通常用于特定集成 web/src/lib/types.ts:66 |
来源： web/src/lib/types.ts:65-73, backend/onyx/auth/schemas.py:47
UserGroup 实体
UserGroups 将用户与 ConnectorCredentialPairs 和 DocumentSets 连接起来，定义了谁可以访问哪些数据。
来源： backend/onyx/db/models.py:1120-1160, web/src/lib/types.ts:109-131
后台处理与协调
系统依赖 Celery 处理长时间运行的异步任务，并通过 Redis 协调以确保任务安全并防止竞态条件。
关键任务类型与状态
| 任务名称 | 代码标识符 | 目的 |
|---|---|---|
| 索引 | IndexingStatus | 跟踪特定索引尝试的状态 backend/onyx/db/enums.py:38 |
| 修剪 | SyncType.PRUNING | 识别并从索引中删除已删除的源文档 backend/onyx/db/enums.py:105 |
| Vespa 同步 | SyncType.DOCUMENT_SET | 将元数据和权限从 Postgres 同步到 Vespa backend/onyx/db/enums.py:102 |
来源： backend/onyx/db/enums.py:38-59, backend/onyx/db/enums.py:101-108
协调与锁定
Redis 用于实现"围栏"模式，确保某些操作（例如索引同一个 CC 对）不会同时发生。
来源： backend/onyx/redis/redis_pool.py:138-139, backend/onyx/db/models.py:118-118
实体汇总表
| 概念 | 后端模型（SQLAlchemy） | 前端类型（TypeScript） |
|---|---|---|
| 用户 | User backend/onyx/db/models.py:129 | User web/src/lib/types.ts:109 |
| 连接器 | Connector backend/onyx/db/models.py:410 | Connector web/src/lib/types.ts:3 |
| 凭证 | Credential backend/onyx/db/models.py:254 | Credential web/src/lib/types.ts:2 |
| CC 对 | ConnectorCredentialPair backend/onyx/db/models.py:445 | ConnectorIndexingStatusLite web/src/lib/types.ts:17 |
| 助手 | Persona backend/onyx/db/models.py:680 | Persona web/src/lib/types.ts:1 |
| 组 | UserGroup backend/onyx/db/models.py:1120 | UserGroup（隐式） |
| 消息 | ChatMessage backend/onyx/db/models.py:890 | ChatMessage（接口） |
来源： backend/onyx/db/models.py:1-1200, web/src/lib/types.ts:1-300