agentic_huge_data_base / wiki
页面 Onyx · 8.5 文档检索与索引后端·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 8.5

8.5 · 文档检索与索引后端（Document Search and Indexing Backends）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节8.5 状态全文译文 模块检索、召回与索引、文档对象与元数据、测试、发布与运维、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Document Search and Indexing Backends 上一章8.4 下一章8.6
源码线索
  • backend/alembic/versions/631fd2504136_add_approx_chunk_count_in_vespa_to_.py
  • backend/onyx/background/celery/tasks/opensearch_migration/constants.py
  • backend/onyx/background/celery/tasks/opensearch_migration/tasks.py
  • backend/onyx/background/celery/tasks/opensearch_migration/transformer.py
  • backend/onyx/connectors/models.py
  • backend/onyx/context/search/retrieval/search_runner.py
  • backend/onyx/db/document.py
  • backend/onyx/db/opensearch_migration.py
  • backend/onyx/document_index/FILTER_SEMANTICS.md
  • backend/onyx/document_index/interfaces.py
模块标签
  • 检索、召回与索引
  • 文档对象与元数据
  • 测试、发布与运维
  • 接口与服务契约
  • 界面与交互

章节正文

文档检索与索引后端

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/8.5-document-search-and-indexing-backends

文档搜索与索引后端

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • backend/alembic/versions/631fd2504136_add_approx_chunk_count_in_vespa_to_.py
  • backend/onyx/background/celery/tasks/opensearch_migration/constants.py
  • backend/onyx/background/celery/tasks/opensearch_migration/tasks.py
  • backend/onyx/background/celery/tasks/opensearch_migration/transformer.py
  • backend/onyx/connectors/models.py
  • backend/onyx/context/search/retrieval/search_runner.py
  • backend/onyx/db/document.py
  • backend/onyx/db/opensearch_migration.py
  • backend/onyx/document_index/FILTER_SEMANTICS.md
  • backend/onyx/document_index/interfaces.py
  • backend/onyx/document_index/interfaces_new.py
  • backend/onyx/document_index/opensearch/client.py
  • backend/onyx/document_index/opensearch/constants.py
  • backend/onyx/document_index/opensearch/opensearch_document_index.py
  • backend/onyx/document_index/opensearch/schema.py
  • backend/onyx/document_index/opensearch/search.py
  • backend/onyx/document_index/vespa/chunk_retrieval.py
  • backend/onyx/document_index/vespa/index.py
  • backend/onyx/document_index/vespa/indexing_utils.py
  • backend/onyx/document_index/vespa/shared_utils/utils.py
  • backend/onyx/document_index/vespa/shared_utils/vespa_request_builders.py
  • backend/onyx/document_index/vespa/vespa_document_index.py
  • backend/onyx/document_index/vespa_constants.py
  • backend/onyx/indexing/adapters/document_indexing_adapter.py
  • backend/onyx/indexing/adapters/user_file_indexing_adapter.py
  • backend/onyx/indexing/chunker.py
  • backend/onyx/indexing/indexing_pipeline.py
  • backend/onyx/indexing/models.py
  • backend/onyx/redis/lock_context.py
  • backend/onyx/server/manage/opensearch_migration/api.py
  • backend/onyx/server/manage/opensearch_migration/models.py
  • backend/onyx/server/metrics/opensearch_search.py
  • backend/onyx/server/onyx_api/ingestion.py
  • backend/scripts/query_time_check/seed_dummy_docs.py
  • backend/tests/external_dependency_unit/celery/test_persona_file_sync.py
  • backend/tests/external_dependency_unit/celery/test_user_file_indexing_adapter.py
  • backend/tests/external_dependency_unit/opensearch/test_assistant_knowledge_filter.py
  • backend/tests/external_dependency_unit/opensearch/test_opensearch_client.py
  • backend/tests/external_dependency_unit/opensearch_migration/test_opensearch_migration_tasks.py
  • backend/tests/external_dependency_unit/redis/test_lock_context.py
  • backend/tests/integration/tests/opensearch_migration/test_opensearch_migration_api.py
  • backend/tests/unit/onyx/document_index/vespa/shared_utils/test_utils.py
  • backend/tests/unit/onyx/indexing/test_embedder.py
  • backend/tests/unit/onyx/indexing/test_indexing_pipeline.py
  • backend/tests/unit/onyx/indexing/test_personas_in_chunks.py
  • backend/tests/unit/onyx/utils/test_vespa_query.py
  • backend/tests/unit/server/metrics/test_opensearch_search_metrics.py
  • profiling/grafana/dashboards/onyx/opensearch-search-latency.json
  • web/src/app/admin/document-index-migration/page.tsx

本文档介绍了 Onyx 中的文档索引实现，重点聚焦于 Vespa 和 OpenSearch 两个后端。内容涵盖索引管线、搜索检索逻辑（混合搜索、过滤）以及从 Vespa 迁移到 OpenSearch 的架构路径。

1. 文档索引架构

Onyx 采用可插拔的文档索引架构，由 DocumentIndex 接口定义 backend/onyx/document_index/interfaces_new.py:39-44。该系统支持两个主要后端：

  1. Vespa：传统高性能引擎，支持复杂排序和大规模向量搜索。
  2. OpenSearch：现代默认后端，提供稳健的混合搜索和标准企业级搜索能力。

后端的选择由环境配置决定，系统提供了从 Vespa 向 OpenSearch 迁移数据的路径。

数据流：索引管线

索引管线将来自连接器的原始文档转换为所选后端中可搜索的片段。

Onyx · 数据流：索引管线 · 图 1
Onyx · 数据流：索引管线 · 图 1

来源： backend/onyx/indexing/indexing_pipeline.py:143-148、backend/onyx/indexing/embedder.py:65-66、backend/onyx/document_index/interfaces_new.py:39-44

2. Vespa 实现

Vespa 通过 VespaDocumentIndex 类实现 backend/onyx/document_index/vespa/vespa_document_index.py:59。它使用 YQL（Yahoo! 查询语言）进行复杂的检索和排序。

片段检索与搜索

Vespa 搜索支持混合搜索，结合了 BM25 关键词匹配与向量相似度。

  • 关键词搜索：使用 weakAnd 操作符进行高效的 Top-K 检索 backend/onyx/document_index/vespa/chunk_retrieval.py:41-50。
  • 向量搜索：利用 HNSW 索引进行近似最近邻搜索 backend/onyx/document_index/vespa/index.py:163-175。
  • 时效性偏好：Vespa 的排序配置文件中包含 RECENCY_BIAS_MULTIPLIER 和 DOC_TIME_DECAY，用于优先展示较新的文档 backend/onyx/document_index/vespa/vespa_document_index.py:14-16。
索引与更新

Vespa 索引以批量方式处理，以优化吞吐量 backend/onyx/document_index/vespa/vespa_constants.py:60。当文档被重新索引时，系统会通过 _enrich_basic_chunk_info 计算新旧片段数量之间的差异，以识别并删除孤立片段 backend/onyx/document_index/vespa/vespa_document_index.py:77-136。

来源： backend/onyx/document_index/vespa/vespa_document_index.py:59-136、backend/onyx/document_index/vespa/index.py:163-175、backend/onyx/document_index/vespa/chunk_retrieval.py:41-50

3. OpenSearch 实现

OpenSearch 通过 OpenSearchDocumentIndex 类实现 backend/onyx/document_index/opensearch/opensearch_document_index.py:39。

混合搜索与归一化

OpenSearch 通过执行多个子查询（向量和关键词）并使用带有归一化处理器的搜索管线合并结果，从而实现混合搜索。

组件描述代码参考
子查询组合标题/内容向量 + 组合关键词搜索backend/onyx/document_index/opensearch/search.py:68-103
归一化使用 Min-Max 或 Z-Score 技术对齐分数backend/onyx/document_index/opensearch/search.py:116-157
权重可配置的权重（例如 0.5 向量、0.5 关键词）backend/onyx/document_index/opensearch/search.py:68-113
模式与字段语义

OpenSearch 文档由 DocumentSchema 定义 backend/onyx/document_index/opensearch/schema.py:178。

  • KNN 引擎：使用 lucene 进行向量搜索 backend/onyx/document_index/opensearch/schema.py:68。
  • ID 生成：get_opensearch_doc_chunk_id 通过组合租户 ID、消毒后的文档 ID（如果过长则进行哈希处理）和片段索引来生成唯一标识符 backend/onyx/document_index/opensearch/schema.py:71-130。

来源： backend/onyx/document_index/opensearch/opensearch_document_index.py:39-139、backend/onyx/document_index/opensearch/search.py:68-157、backend/onyx/document_index/opensearch/schema.py:68-130

4. 过滤语义与访问控制

两个后端都强制执行严格的过滤，以确保安全性和相关性。过滤器封装在 IndexFilters 模型中 backend/onyx/context/search/models.py:30。

核心过滤器
  1. 访问控制列表（ACL）：通过 access_control_list 过滤文档，确保用户只能看到其有权访问的内容 backend/onyx/document_index/opensearch/schema.py:43。
  2. 文档集：按管理员定义的特定集合进行过滤 backend/onyx/document_index/opensearch/schema.py:49。
  3. 来源类型：通过 SOURCE_TYPE_FIELD_NAME 将搜索限制到特定的连接器 backend/onyx/document_index/opensearch/schema.py:39。
  4. 时间过滤器：使用范围查询按 last_updated 进行过滤 backend/onyx/document_index/opensearch/schema.py:41。
代码实体映射：搜索逻辑

下图将搜索概念映射到实现它们的代码实体。

Onyx · 代码实体映射：搜索逻辑 · 图 2
Onyx · 代码实体映射：搜索逻辑 · 图 2

来源： backend/onyx/context/search/models.py:30、backend/onyx/document_index/opensearch/search.py:61、backend/onyx/document_index/vespa/chunk_retrieval.py:49

5. OpenSearch 迁移路径

Onyx 提供了从 Vespa 到 OpenSearch 的受管迁移路径。该路径通过 migrate_chunks_from_vespa_to_opensearch_task Celery 任务进行编排。

迁移工作流
  1. 初始化：迁移任务通过 set_cluster_state 创建目标 OpenSearch 索引和搜索管线 backend/onyx/document_index/opensearch/opensearch_document_index.py:116-139。
  2. 数据转换：使用 Visit API 从 Vespa 读取文档，由 transform_vespa_chunks_to_opensearch_chunks 工具转换为 OpenSearch 模式格式，然后索引到 OpenSearch 中 backend/onyx/background/celery/tasks/opensearch_migration/transformer.py:12-14。
  3. 进度跟踪：使用存储在 PostgreSQL 中 OpenSearchTenantMigrationRecord 内的连续令牌来跟踪进度 backend/onyx/db/opensearch_migration.py:46。
  4. 切换：迁移完成后，系统会切换其活动的 DocumentIndex 实现 backend/onyx/db/opensearch_migration.py:39。
代码实体映射：迁移基础设施

此图显示了迁移任务与底层存储客户端之间的关系。

Onyx · 代码实体映射：迁移基础设施 · 图 3
Onyx · 代码实体映射：迁移基础设施 · 图 3

来源： backend/onyx/document_index/opensearch/client.py:113、backend/onyx/document_index/vespa/index.py:59、backend/onyx/background/celery/tasks/opensearch_migration/transformer.py:12

6. 模型服务器集成

搜索后端依赖模型服务器来生成嵌入向量。

  • 嵌入器：IndexingEmbedder 管理片段流向模型服务器的流程 backend/onyx/indexing/embedder.py:65。
  • 批处理：使用 MAX_CHUNKS_PER_DOC_BATCH 对嵌入向量进行批量处理，以优化网络和计算开销 backend/onyx/indexing/indexing_pipeline.py:15。
  • 精度：虽然 Vespa 支持多种精度，但无论 EmbeddingPrecision 设置如何，OpenSearch 都会将向量存储为 float32 类型 backend/onyx/indexing/models.py:192-195。

来源： backend/onyx/indexing/embedder.py:65-66、backend/onyx/indexing/indexing_pipeline.py:15、backend/onyx/indexing/models.py:192-195