> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-fix-template-upload-size-guidance.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建空知识库

> 创建一个空知识库。之后用 [从文本创建文档](/zh/api-reference/documents/create-document-by-text) 或 [从文件创建文档](/zh/api-reference/documents/create-document-by-file) 向其中添加文档。



## OpenAPI

````yaml /zh/api-reference/openapi_service.json post /datasets
openapi: 3.0.1
info:
  description: 用于 Dify 应用与知识库的 REST API。应用类接口使用应用 API 密钥认证，知识库类接口使用知识库 API 密钥认证。
  title: Dify 服务 API
  version: 1.0.0
servers:
  - description: Dify 服务 API 的基础 URL。自部署时，替换为你的 API 基础 URL。
    url: https://{api_base_url}
    variables:
      api_base_url:
        default: api.dify.ai/v1
        description: API 基础 URL 的主机与路径，不含 `https://` 前缀。
security:
  - ApiKeyAuth: []
tags:
  - description: 与聊天消息和交互相关的操作。
    name: 对话消息
  - description: 文件上传和预览操作。
    name: 文件操作
  - description: 终端用户信息相关操作。
    name: 终端用户
  - description: 用户反馈操作。
    name: 消息反馈
  - description: 与管理会话相关的操作。
    name: 会话管理
  - description: 文字转语音和语音转文字操作。
    name: 语音与文字转换
  - description: 获取应用设置和信息的操作。
    name: 应用配置
  - description: 与管理标注直接回复相关的操作。
    name: 标注管理
  - description: 暂停等待人工输入的工作流恢复操作。
    name: 人工介入
  - description: 用于执行和管理工作流的操作。
    name: 工作流运行
  - description: 文本生成相关操作。
    name: 文本生成消息
  - description: 用于管理知识库的操作，包括创建、配置和检索。
    name: 知识库
  - description: 用于在知识库中创建、更新和管理文档的操作。
    name: 文档
  - description: 用于管理分段和子分段的操作。
    name: 分段
  - description: 用于管理知识库元数据字段和文档元数据值的操作。
    name: 元数据
  - description: 用于管理知识库标签和标签绑定的操作。
    name: 标签
  - description: 用于获取可用模型的操作。
    name: 模型
  - description: 用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。
    name: 知识流水线
paths:
  /datasets:
    post:
      tags:
        - 知识库
      summary: 创建空知识库
      description: >-
        创建一个空知识库。之后用
        [从文本创建文档](/zh/api-reference/documents/create-document-by-text) 或
        [从文件创建文档](/zh/api-reference/documents/create-document-by-file) 向其中添加文档。
      operationId: createDataset
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  default: ''
                  description: 知识库描述。
                  maxLength: 400
                  type: string
                embedding_model:
                  description: >-
                    嵌入模型名称。使用
                    [获取可用模型](/zh/api-reference/models/get-available-models) 中
                    `model_type=text-embedding` 返回的 `model` 字段值。
                  type: string
                embedding_model_provider:
                  description: >-
                    嵌入模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如
                    `langgenius/openai/openai`）。`openai` 这类简写会展开为
                    `langgenius/<name>/<name>`，仅对 langgenius 发布的插件有效。


                    有效取值从
                    [获取可用模型](/zh/api-reference/models/get-available-models) 中
                    `model_type=text-embedding` 返回的 `provider` 字段获取。
                  type: string
                external_knowledge_api_id:
                  description: 外部知识库 API 连接的 ID。
                  type: string
                external_knowledge_id:
                  description: 外部知识库的 ID。
                  type: string
                indexing_technique:
                  description: '`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。'
                  enum:
                    - high_quality
                    - economy
                  nullable: true
                  type: string
                name:
                  description: 知识库名称。
                  maxLength: 40
                  minLength: 1
                  type: string
                permission:
                  default: only_me
                  description: >-
                    控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members`
                    授权整个工作区访问，`partial_members` 授权指定成员访问。
                  enum:
                    - only_me
                    - all_team_members
                    - partial_members
                  type: string
                provider:
                  default: vendor
                  description: '`vendor` 为内部知识库，`external` 为外部知识库。'
                  enum:
                    - vendor
                    - external
                  type: string
                retrieval_model:
                  $ref: '#/components/schemas/RetrievalModel'
                  description: 检索模型配置。控制查询此知识库时如何搜索和排序分段。
                summary_index_setting:
                  description: 摘要索引配置。
                  nullable: true
                  properties:
                    enable:
                      description: 是否启用摘要索引。
                      type: boolean
                    model_name:
                      description: 用于生成摘要的模型名称。
                      type: string
                    model_provider_name:
                      description: 摘要生成模型的供应商。
                      type: string
                    summary_prompt:
                      description: 用于摘要生成的自定义提示词模板。
                      type: string
                  type: object
              required:
                - name
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  summary: 响应示例
                  value:
                    app_count: 0
                    author_name: admin
                    built_in_field_enabled: true
                    chunk_structure: null
                    created_at: 1741267200
                    created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                    data_source_type: null
                    description: 产品 API 技术文档
                    doc_form: text_model
                    doc_metadata: []
                    document_count: 0
                    embedding_available: true
                    embedding_model: text-embedding-3-small
                    embedding_model_provider: langgenius/openai/openai
                    enable_api: true
                    external_knowledge_info: null
                    external_retrieval_model: null
                    icon_info: null
                    id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
                    indexing_technique: high_quality
                    is_multimodal: false
                    is_published: false
                    maintainer: admin
                    name: Product Documentation
                    permission: only_me
                    pipeline_id: null
                    provider: vendor
                    retrieval_model_dict:
                      reranking_enable: false
                      reranking_mode: null
                      reranking_model:
                        reranking_model_name: ''
                        reranking_provider_name: ''
                      score_threshold: null
                      score_threshold_enabled: false
                      search_method: semantic_search
                      top_k: 3
                      weights: null
                    runtime_mode: null
                    summary_index_setting: null
                    tags: []
                    total_available_documents: 0
                    total_documents: 0
                    updated_at: 1741267200
                    updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                    word_count: 0
              schema:
                $ref: '#/components/schemas/Dataset'
          description: 知识库创建成功。
        '400':
          content:
            application/json:
              examples:
                invalid_param:
                  summary: invalid_param
                  value:
                    code: invalid_param
                    message: >-
                      No Embedding Model available. Please configure a valid
                      provider in the Settings -> Model Provider.
                    status: 400
          description: '`invalid_param` : 指定的嵌入模型或重排序模型未配置或不可用。'
        '403':
          content:
            application/json:
              examples:
                forbidden:
                  summary: forbidden (rate limit)
                  value:
                    code: forbidden
                    message: >-
                      Sorry, you have reached the knowledge base request rate
                      limit of your subscription.
                    status: 403
          description: '`forbidden` : 已达到您订阅套餐的知识库请求速率限制。'
        '409':
          content:
            application/json:
              examples:
                dataset_name_duplicate:
                  summary: dataset_name_duplicate
                  value:
                    code: dataset_name_duplicate
                    message: >-
                      The dataset name already exists. Please modify your
                      dataset name.
                    status: 409
          description: '`dataset_name_duplicate` : 已存在同名知识库。'
components:
  schemas:
    RetrievalModel:
      properties:
        metadata_filtering_conditions:
          description: 仅检索文档元数据匹配指定条件的分段。条件由服务端基于文档元数据字段评估。
          nullable: true
          properties:
            conditions:
              description: 要评估的元数据条件列表。
              items:
                properties:
                  comparison_operator:
                    description: >-
                      按元数据类型选择要应用的比较方式：


                      - 字符串或数组类型元数据：`contains`、`not contains`、`start with`、`end
                      with`、`is`、`is not`、`empty`、`not empty`、`in`、`not in`

                      - 数值类型元数据：`=`、`≠`、`>`、`<`、`≥`、`≤`

                      - 时间类型元数据：`before`、`after`
                    enum:
                      - contains
                      - not contains
                      - start with
                      - end with
                      - is
                      - is not
                      - empty
                      - not empty
                      - in
                      - not in
                      - '='
                      - ≠
                      - '>'
                      - <
                      - ≥
                      - ≤
                      - before
                      - after
                    type: string
                  name:
                    description: 用于比较的元数据字段名称。
                    type: string
                  value:
                    description: >-
                      用于比较的值。类型取决于 `comparison_operator`：大多数字符串运算符使用字符串；`in` 和
                      `not in` 使用字符串数组；数值运算符使用数字；`empty` 和 `not empty` 时省略。
                    nullable: true
                    oneOf:
                      - type: string
                      - items:
                          type: string
                        type: array
                      - type: number
                required:
                  - name
                  - comparison_operator
                type: object
              nullable: true
              type: array
            logical_operator:
              default: and
              description: 多个条件之间的组合方式。
              enum:
                - and
                - or
              nullable: true
              type: string
          type: object
        reranking_enable:
          description: 是否启用重排序。
          type: boolean
        reranking_mode:
          description: 重排序模式。当 `reranking_enable` 为 `true` 时必填。
          enum:
            - reranking_model
            - weighted_score
          nullable: true
          type: string
        reranking_model:
          description: 重排序模型配置。
          properties:
            reranking_model_name:
              description: 重排序模型名称。
              type: string
            reranking_provider_name:
              description: >-
                重排序模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如
                `langgenius/cohere/cohere`）。`cohere` 这类简写会展开为
                `langgenius/<name>/<name>`，仅对 langgenius 发布的插件有效。


                有效取值从 [获取可用模型](/zh/api-reference/models/get-available-models) 中
                `model_type=rerank` 返回的 `provider` 字段获取。
              type: string
          type: object
        score_threshold:
          description: 结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。
          nullable: true
          type: number
        score_threshold_enabled:
          description: 是否启用分数阈值过滤。
          type: boolean
        search_method:
          description: 用于检索的搜索方法。
          enum:
            - keyword_search
            - semantic_search
            - full_text_search
            - hybrid_search
          type: string
        top_k:
          description: 返回的最大结果数。
          type: integer
        weights:
          description: 混合搜索的权重配置。
          nullable: true
          properties:
            keyword_setting:
              description: 关键词搜索权重设置。
              properties:
                keyword_weight:
                  description: 分配给关键词搜索结果的权重。
                  type: number
              type: object
            vector_setting:
              description: 语义搜索权重设置。
              properties:
                embedding_model_name:
                  description: 用于向量搜索的嵌入模型名称。
                  type: string
                embedding_provider_name:
                  description: 用于向量搜索的嵌入模型供应商。
                  type: string
                vector_weight:
                  description: 分配给语义（向量）搜索结果的权重。
                  type: number
              type: object
            weight_type:
              description: 平衡语义搜索和关键词搜索权重的策略。
              enum:
                - semantic_first
                - keyword_first
                - customized
              type: string
          type: object
      required:
        - search_method
        - reranking_enable
        - top_k
        - score_threshold_enabled
      type: object
    Dataset:
      properties:
        app_count:
          description: 当前使用该知识库的应用数量。
          type: integer
        author_name:
          description: 创建者的显示名称。
          type: string
        built_in_field_enabled:
          description: 是否启用内置元数据字段（例如 `document_name`、`uploader`）。
          type: boolean
        chunk_structure:
          description: 分段结构配置。
          nullable: true
          type: string
        created_at:
          description: 创建时间戳（Unix 纪元，单位为秒）。
          type: number
        created_by:
          description: 创建该知识库的用户 ID。
          type: string
        data_source_type:
          description: 文档的数据源类型，尚未配置时为 `null`。
          type: string
        description:
          description: 描述知识库用途或内容的可选文本。
          type: string
        doc_form:
          description: >-
            文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model`
            表示问答对提取。
          type: string
        doc_metadata:
          description: 知识库的元数据字段定义。
          items:
            properties:
              id:
                description: 元数据字段标识符。
                type: string
              name:
                description: 元数据字段名称。
                type: string
              type:
                description: 元数据字段值类型。
                type: string
            type: object
          type: array
        document_count:
          description: 知识库中的文档总数。
          type: integer
        embedding_available:
          description: 配置的嵌入模型当前是否可用。
          type: boolean
        embedding_model:
          description: 用于索引的嵌入模型名称。
          type: string
        embedding_model_provider:
          description: >-
            嵌入模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如
            `langgenius/openai/openai`）。旧版知识库可能返回简写形式（例如 `openai`）。
          type: string
        enable_api:
          description: 该知识库是否启用 API 访问。
          type: boolean
        external_knowledge_info:
          description: 外部知识库的连接详情。当 `provider` 为 `external` 时存在。
          nullable: true
          properties:
            external_knowledge_api_endpoint:
              description: 外部知识库 API 的端点 URL。
              type: string
            external_knowledge_api_id:
              description: 外部知识库 API 连接的 ID。
              type: string
            external_knowledge_api_name:
              description: 外部知识库 API 的显示名称。
              type: string
            external_knowledge_id:
              description: 外部知识库的 ID。
              type: string
          type: object
        external_retrieval_model:
          description: 外部知识库的检索设置。内部知识库时为 `null`。
          nullable: true
          properties:
            score_threshold:
              description: 最低相关性得分阈值。
              type: number
            score_threshold_enabled:
              description: 是否启用分数阈值过滤。
              type: boolean
            top_k:
              description: 从外部知识库返回的最大结果数量。
              type: integer
          type: object
        icon_info:
          description: 知识库的图标显示配置。
          nullable: true
          properties:
            icon:
              description: 图标标识符或表情符号。
              type: string
            icon_background:
              description: 图标的背景颜色。
              type: string
            icon_type:
              description: 图标类型。
              type: string
            icon_url:
              description: 自定义图标图片的 URL。
              type: string
          type: object
        id:
          description: 知识库的唯一标识符。
          type: string
        indexing_technique:
          description: '`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。'
          type: string
        is_multimodal:
          description: 是否启用多模态内容处理。
          type: boolean
        is_published:
          description: 知识库是否已发布。
          type: boolean
        maintainer:
          description: 知识库维护者的显示名称。未设置时为 `null`。
          nullable: true
          type: string
        name:
          description: 知识库的显示名称。在工作区内唯一。
          type: string
        partial_member_list:
          description: >-
            当 `permission` 为 `partial_members` 时被授予访问权限的成员账户
            ID。更新响应中始终返回；详情响应中仅当 `permission` 为 `partial_members` 时返回。
          items:
            type: string
          nullable: true
          type: array
        permission:
          description: 控制谁可以访问此知识库。可选值：`only_me`、`all_team_members`、`partial_members`。
          type: string
        pipeline_id:
          description: 自定义处理流水线的 ID（如果已配置）。
          nullable: true
          type: string
        provider:
          description: 供应商类型。内部管理为 `vendor`，外部知识库连接为 `external`。
          type: string
        retrieval_model_dict:
          description: 知识库的检索配置。
          properties:
            reranking_enable:
              description: 是否启用重排序。
              type: boolean
            reranking_mode:
              description: >-
                重排序模式。`reranking_model` 表示基于模型的重排序，`weighted_score`
                表示基于分数的加权。重排序禁用时为 `null`。
              nullable: true
              type: string
            reranking_model:
              description: 重排序模型配置。
              properties:
                reranking_model_name:
                  description: 重排序模型名称。
                  type: string
                reranking_provider_name:
                  description: >-
                    重排序模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如
                    `langgenius/cohere/cohere`）。旧版知识库可能返回简写形式（例如 `cohere`）。
                  type: string
              type: object
            score_threshold:
              description: 结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。
              type: number
            score_threshold_enabled:
              description: 是否启用分数阈值过滤。
              type: boolean
            search_method:
              description: >-
                用于检索的搜索方式。`keyword_search` 表示关键词匹配，`semantic_search`
                表示基于嵌入的语义相似度，`full_text_search` 表示全文索引，`hybrid_search`
                表示语义和关键词混合搜索。
              type: string
            top_k:
              description: 返回的最大结果数。
              type: integer
            weights:
              description: 混合搜索的权重配置。
              nullable: true
              properties:
                keyword_setting:
                  description: 关键词搜索权重设置。
                  properties:
                    keyword_weight:
                      description: 分配给关键词搜索结果的权重。
                      type: number
                  type: object
                vector_setting:
                  description: 语义搜索权重设置。
                  properties:
                    embedding_model_name:
                      description: 用于向量搜索的嵌入模型名称。
                      type: string
                    embedding_provider_name:
                      description: 用于向量搜索的嵌入模型供应商。
                      type: string
                    vector_weight:
                      description: 分配给语义（向量）搜索结果的权重。
                      type: number
                  type: object
                weight_type:
                  description: 平衡语义搜索和关键词搜索权重的策略。
                  type: string
              type: object
          type: object
        runtime_mode:
          description: 运行时处理模式。
          nullable: true
          type: string
        summary_index_setting:
          description: 摘要索引配置。
          nullable: true
          properties:
            enable:
              description: 是否已启用摘要索引。
              type: boolean
            model_name:
              description: 用于生成摘要的模型名称。
              type: string
            model_provider_name:
              description: 摘要生成模型的供应商。
              type: string
            summary_prompt:
              description: 用于摘要生成的提示词模板。
              type: string
          type: object
        tags:
          description: 与该知识库关联的标签。
          items:
            properties:
              id:
                description: 标签标识符。
                type: string
              name:
                description: Tag name.
                type: string
              type:
                description: 标签类型。知识库标签始终为 `knowledge`。
                type: string
            type: object
          type: array
        total_available_documents:
          description: 已启用且可用的文档数量。
          type: integer
        total_documents:
          description: 文档总数。
          type: integer
        updated_at:
          description: 最后更新时间戳（Unix 纪元，单位为秒）。
          type: number
        updated_by:
          description: 最后更新该知识库的用户 ID。
          type: string
        word_count:
          description: 所有文档的总字数。
          type: integer
      type: object
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: API_KEY
      description: >-
        每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API
        Key，知识库接口使用知识库 API Key（[快速开始](/zh/api-reference/guides/get-started)）。


        API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。
      scheme: bearer
      type: http

````