7.4 · 数据集与知识库 API（Dataset and Knowledge Base APIs）

复杂文档理解与引用检索 · 本章是 RAGFlow DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目RAGFlow 章节7.4 状态全文译文模块测试、发布与运维、检索、召回与索引、界面与交互、入库与解析

项目要点页2.5 参考项目项目章节目录RAGFlow DeepWiki 原始章节Dataset and Knowledge Base APIs 上一章7.3 下一章7.5

源码线索

api/apps/backward_compat.py
api/apps/restful_apis/chunk_api.py
api/apps/restful_apis/dataset_api.py
api/apps/sdk/dify_retrieval.py
api/apps/sdk/doc.py
api/apps/sdk/session.py
api/apps/services/dataset_api_service.py
api/db/joint_services/tenant_model_service.py
api/utils/validation_utils.py
docs/references/http_api_reference.md

模块标签

测试、发布与运维
检索、召回与索引
界面与交互
入库与解析
图谱与关系

中文译文

数据集与知识库 API（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/infiniflow/ragflow/7.4-dataset-and-knowledge-base-apis

翻译时间：2026-05-27T08:44:30.585Z

翻译模型：deepseek-chat

原文字符数：14760

项目：RAGFlow (ragflow)

---

数据集与知识库 API

目的与范围

本文档记录了 RAGFlow 中用于创建、配置和管理数据集（也称为知识库）的 REST API 端点及底层服务架构。数据集作为文档的逻辑容器，定义了关键的处理参数，包括解析策略、嵌入向量模型和访问权限。

有关数据集内的文档上传和管理，请参阅文档与文件管理 API。有关聊天操作期间的数据检索，请参阅聊天与会话 API。

数据集资源模型

RAGFlow 中的数据集由 api/db/db_models.py 中定义的 Knowledgebase 模型表示。它封装了以下技术属性：

标识：唯一 ID、名称、描述和头像 api/db/db_models.py:595-605。
解析配置：parser_id（片段切分方法）和方法特定的 parser_config 设置 api/db/db_models.py:611-615。
嵌入向量模型：用于向量化文档片段的特定模型（embd_id）api/db/db_models.py:610-610。
访问控制：权限级别（me 或 team）api/db/db_models.py:616-616。
统计信息：反规范化的计数器，包括文档数、片段数和 Token 数 api/db/db_models.py:618-621。
高级功能：RAPTOR、GraphRAG 和 PageIndex（原 ToC）的设置 docs/release_notes.md:108-110，api/db/db_models.py:623-625。

数据集-文档-片段关系

标题："数据集层级与存储映射"

graph TB
    subgraph "数据集层"
        KB["Knowledgebase_(数据集)<br/>id, name, parser_id, embd_id<br/>parser_config, permission"]
    end

    subgraph "文档层"
        Doc1["文档_1<br/>kb_id, parser_id<br/>name, size, status"]
        Doc2["文档_2"]
        DocN["文档_N"]
    end

    subgraph "存储层"
        Chunks["文档存储中的片段<br/>Elasticsearch/Infinity/OceanBase<br/>kb_id, doc_id, vectors"]
        MinIO["MinIO 中的原始文件<br/>kb_id, location"]
        MySQL["MySQL/PostgreSQL 中的元数据<br/>kb_id, doc_id"]
    end

    KB -->|"1:N"| Doc1
    KB -->|"1:N"| Doc2
    KB -->|"1:N"| DocN

    Doc1 --> Chunks
    Doc2 --> Chunks
    DocN --> Chunks

    Doc1 --> MinIO
    Doc2 --> MinIO

    Doc1 --> MySQL
    Doc2 --> MySQL

来源： api/db/db_models.py:595-754，api/db/services/knowledgebase_service.py:32-48，api/db/services/document_service.py:45-76

核心数据集操作

创建数据集

端点： POST /api/v1/datasets

创建一个新的数据集。请求通过 api/apps/services/dataset_api_service.py 中的 create_dataset 处理，该函数负责元数据配置和嵌入向量模型验证 api/apps/services/dataset_api_service.py:54-107。

标题："数据集创建流程"

graph LR
    Request["POST_/api/v1/datasets<br/>Authorization:_Bearer_token<br/>Content-Type:_application/json"]

    SDK["ragflow_sdk.RAGFlow.create_dataset"]
    Service["dataset_api_service.create_dataset"]
    DB_KB["KnowledgebaseService.create_with_name"]

    Request --> SDK
    SDK --> Service
    Service --> DB_KB

    DB_KB --> Validate["verify_embedding_availability"]
    Validate --> Save["KnowledgebaseService.save()"]

    Save --> Index["settings.docStoreConn.create_idx()<br/>Initialize_vector_index"]

关键参数：

参数	类型	必填	描述
`name`	字符串	是	唯一的数据集名称（最多 128 个字符）`docs/references/python_api_reference.md:142-147`
`embedding_model`	字符串	否	格式：`model_name@factory` `docs/references/python_api_reference.md:131-131`
`permission`	枚举	否	`"me"`（默认）或 `"team"` `docs/references/python_api_reference.md:160-163`
`chunk_method`	枚举	否	解析器类型（例如 `naive`、`qa`、`manual`）`docs/references/python_api_reference.md:165-180`
`parser_config`	对象	否	方法特定的配置 `docs/references/python_api_reference.md:181-209`
`auto_metadata_config`	对象	否	基于大语言模型（LLM）的自动元数据提取配置 `api/apps/services/dataset_api_service.py:66-82`

来源： docs/references/http_api_reference.md:440-643，sdk/python/ragflow_sdk/ragflow.py:56-84，api/apps/services/dataset_api_service.py:54-107

列出和删除数据集

端点： GET /api/v1/datasets，DELETE /api/v1/datasets

删除过程由服务层的 delete_datasets 处理，该函数会从数据库和文档存储（Elasticsearch/Infinity）中级联删除关联的文档 api/apps/services/dataset_api_service.py:110-174。

来源： api/apps/services/dataset_api_service.py:110-174，sdk/python/ragflow_sdk/ragflow.py:86-116

解析器与任务管理

解析器选择工厂

系统支持多种片段切分方法。支持的方法包括 naive、qa、table、paper、book、laws、presentation、picture、one、email 和 knowledge-graph docs/references/python_api_reference.md:165-209。

知识库增强任务

高级知识库功能通过 TaskService 触发后台任务。

GraphRAG：用于基于图的检索的实体和关系提取 api/apps/services/dataset_api_service.py:36-37。
RAPTOR：用于层级摘要的递归抽象处理 api/apps/services/dataset_api_service.py:38-38。
思维导图：可视化知识结构 api/apps/services/dataset_api_service.py:39-39。

api/db/services/document_service.py 中的 queue_raptor_o_graphrag_tasks 函数负责将这些专门任务加入队列 api/apps/services/dataset_api_service.py:23-23。

检索与搜索接口

检索系统支持跨数据集的基于元数据的过滤。SDK 中的 retrieve 方法允许用户使用特定的相似度权重和元数据条件同时查询多个数据集 sdk/python/ragflow_sdk/ragflow.py:187-203。

标题："检索逻辑流程"

graph TB
    API["POST_/api/v1/retrieval"]
    SDK["ragflow_sdk.RAGFlow.retrieve"]
    Retriever["settings.retriever.retrieval"]

    API --> SDK
    SDK --> Retriever

    subgraph "过滤引擎"
        MetaFilter["common.metadata_utils.meta_filter"]
        DocMeta["api.db.services.doc_metadata_service"]
    end

    Retriever --> MetaFilter
    MetaFilter --> DocMeta

元数据过滤逻辑： 检索结果可以使用请求体中的 metadata_condition 进行缩小。系统使用 meta_filter 和 convert_conditions 应用过滤器 api/apps/sdk/dify_retrieval.py:31-31。DocMetadataService 管理用于在搜索引擎执行前缩小文档 ID 范围的元数据 api/apps/sdk/dify_retrieval.py:27-27。

来源： sdk/python/ragflow_sdk/ragflow.py:187-203，api/apps/sdk/dify_retrieval.py:110-185，api/db/services/doc_metadata_service.py:21-21

实现参考

关键服务类

类	角色	文件
`KnowledgebaseService`	数据集的 CRUD 和权限逻辑	`api/db/services/knowledgebase_service.py`
`DocumentService`	文档记录和状态的管理	`api/db/services/document_service.py`
`DocMetadataService`	元数据持久化和批量更新	`api/db/services/doc_metadata_service.py`
`TaskService`	解析/索引任务的生命周期管理	`api/db/services/task_service.py`
`File2DocumentService`	原始文件与文档实体之间的映射	`api/db/services/file2document_service.py`

来源： api/db/services/knowledgebase_service.py:32-48，api/db/services/document_service.py:45-46，api/db/services/doc_metadata_service.py:21-21，api/db/services/task_service.py:28-28，api/db/services/file2document_service.py:25-25