From 8b55d422391a45ce8225e414adc05368d8010ebd Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Mon, 17 Mar 2025 16:24:01 +0800
Subject: [PATCH 01/21] fix: adjust position of table of contents in Doc
 component

---
 web/app/(commonLayout)/datasets/Doc.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/app/(commonLayout)/datasets/Doc.tsx b/web/app/(commonLayout)/datasets/Doc.tsx
index f56a5bc909..554601264d 100644
--- a/web/app/(commonLayout)/datasets/Doc.tsx
+++ b/web/app/(commonLayout)/datasets/Doc.tsx
@@ -68,7 +68,7 @@ const Doc = ({ apiBaseUrl }: DocProps) => {
 
   return (
     <div className="flex">
-      <div className={`fixed right-16 top-32 z-10 transition-all ${isTocExpanded ? 'w-64' : 'w-10'}`}>
+      <div className={`fixed right-20 top-32 z-10 transition-all ${isTocExpanded ? 'w-64' : 'w-10'}`}>
         {isTocExpanded
           ? (
             <nav className="toc w-full bg-gray-50 p-4 rounded-lg shadow-md max-h-[calc(100vh-150px)] overflow-y-auto">

From 9b522bd82049cdd5c57713ead15af3db00a03145 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 13:51:19 +0800
Subject: [PATCH 02/21] feat(api): add child chunk management endpoints for
 segments in dataset API

---
 .../service_api/dataset/segment.py            | 213 +++++++-
 move_section.js                               |   1 +
 .../datasets/template/template.zh.mdx         | 513 +++++++++++-------
 3 files changed, 519 insertions(+), 208 deletions(-)
 create mode 100644 move_section.js

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index 25ae43f2ad..9cbcb15a7a 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -13,10 +13,16 @@ from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
 from core.model_manager import ModelManager
 from core.model_runtime.entities.model_entities import ModelType
 from extensions.ext_database import db
-from fields.segment_fields import segment_fields
-from models.dataset import Dataset, DocumentSegment
+from fields.segment_fields import segment_fields, child_chunk_fields
+from models.dataset import Dataset, DocumentSegment, ChildChunk
 from services.dataset_service import DatasetService, DocumentService, SegmentService
 from services.entities.knowledge_entities.knowledge_entities import SegmentUpdateArgs
+from services.errors.chunk import (
+    ChildChunkDeleteIndexError as ChildChunkDeleteIndexServiceError,
+    ChildChunkIndexingError as ChildChunkIndexingServiceError,
+    ChildChunkIndexingError,
+    ChildChunkDeleteIndexError
+)
 
 
 class SegmentApi(DatasetApiResource):
@@ -195,7 +201,210 @@ class DatasetSegmentApi(DatasetApiResource):
         return {"data": marshal(segment, segment_fields), "doc_form": document.doc_form}, 200
 
 
+class ChildChunkAddApi(DatasetApiResource):
+    """Resource for child chunks."""
+    
+    @cloud_edition_billing_resource_check("vector_space", "dataset")
+    @cloud_edition_billing_knowledge_limit_check("add_segment", "dataset") 
+    def post(self, tenant_id, dataset_id, document_id, segment_id):
+        """Create child chunk."""
+        # check dataset
+        dataset_id = str(dataset_id)
+        tenant_id = str(tenant_id)
+        dataset = db.session.query(Dataset).filter(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id).first()
+        if not dataset:
+            raise NotFound("Dataset not found.")
+
+        # check document
+        document_id = str(document_id)
+        document = DocumentService.get_document(dataset.id, document_id)
+        if not document:
+            raise NotFound("Document not found.")
+
+        # check segment
+        segment_id = str(segment_id)
+        segment = DocumentSegment.query.filter(
+            DocumentSegment.id == str(segment_id), 
+            DocumentSegment.tenant_id == current_user.current_tenant_id
+        ).first()
+        if not segment:
+            raise NotFound("Segment not found.")
+
+        # check embedding model setting
+        if dataset.indexing_technique == "high_quality":
+            try:
+                model_manager = ModelManager()
+                model_manager.get_model_instance(
+                    tenant_id=current_user.current_tenant_id,
+                    provider=dataset.embedding_model_provider,
+                    model_type=ModelType.TEXT_EMBEDDING,
+                    model=dataset.embedding_model,
+                )
+            except LLMBadRequestError:
+                raise ProviderNotInitializeError(
+                    "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
+                )
+            except ProviderTokenNotInitError as ex:
+                raise ProviderNotInitializeError(ex.description)
+
+        # validate args
+        parser = reqparse.RequestParser()
+        parser.add_argument("content", type=str, required=True, nullable=False, location="json")
+        args = parser.parse_args()
+
+        try:
+            child_chunk = SegmentService.create_child_chunk(args.get("content"), segment, document, dataset)
+        except ChildChunkIndexingServiceError as e:
+            raise ChildChunkIndexingError(str(e))
+
+        return {"data": marshal(child_chunk, child_chunk_fields)}, 200
+
+    def get(self, tenant_id, dataset_id, document_id, segment_id):
+        """Get child chunks."""
+        # check dataset
+        dataset_id = str(dataset_id)
+        tenant_id = str(tenant_id)
+        dataset = db.session.query(Dataset).filter(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id).first()
+        if not dataset:
+            raise NotFound("Dataset not found.")
+
+        # check document
+        document_id = str(document_id)
+        document = DocumentService.get_document(dataset.id, document_id)
+        if not document:
+            raise NotFound("Document not found.")
+
+        # check segment
+        segment_id = str(segment_id)
+        segment = DocumentSegment.query.filter(
+            DocumentSegment.id == str(segment_id),
+            DocumentSegment.tenant_id == current_user.current_tenant_id
+        ).first()
+        if not segment:
+            raise NotFound("Segment not found.")
+
+        parser = reqparse.RequestParser()
+        parser.add_argument("limit", type=int, default=20, location="args")
+        parser.add_argument("keyword", type=str, default=None, location="args")
+        parser.add_argument("page", type=int, default=1, location="args")
+        args = parser.parse_args()
+
+        page = args["page"]
+        limit = min(args["limit"], 100)
+        keyword = args["keyword"]
+
+        child_chunks = SegmentService.get_child_chunks(segment_id, document_id, dataset_id, page, limit, keyword)
+        
+        return {
+            "data": marshal(child_chunks.items, child_chunk_fields),
+            "total": child_chunks.total,
+            "total_pages": child_chunks.pages,
+            "page": page,
+            "limit": limit,
+        }, 200
+
+
+class ChildChunkUpdateApi(DatasetApiResource):
+    """Resource for updating child chunks."""
+
+    def delete(self, tenant_id, dataset_id, document_id, segment_id, child_chunk_id):
+        """Delete child chunk."""
+        # check dataset
+        dataset_id = str(dataset_id)
+        tenant_id = str(tenant_id)
+        dataset = db.session.query(Dataset).filter(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id).first()
+        if not dataset:
+            raise NotFound("Dataset not found.")
+
+        # check document
+        document_id = str(document_id)
+        document = DocumentService.get_document(dataset.id, document_id)
+        if not document:
+            raise NotFound("Document not found.")
+
+        # check segment
+        segment_id = str(segment_id)
+        segment = DocumentSegment.query.filter(
+            DocumentSegment.id == str(segment_id),
+            DocumentSegment.tenant_id == current_user.current_tenant_id
+        ).first()
+        if not segment:
+            raise NotFound("Segment not found.")
+
+        # check child chunk
+        child_chunk_id = str(child_chunk_id)
+        child_chunk = ChildChunk.query.filter(
+            ChildChunk.id == str(child_chunk_id),
+            ChildChunk.tenant_id == current_user.current_tenant_id
+        ).first()
+        if not child_chunk:
+            raise NotFound("Child chunk not found.")
+
+        try:
+            SegmentService.delete_child_chunk(child_chunk, dataset)
+        except ChildChunkDeleteIndexServiceError as e:
+            raise ChildChunkDeleteIndexError(str(e))
+
+        return {"result": "success"}, 200
+
+    @cloud_edition_billing_resource_check("vector_space", "dataset")
+    def patch(self, tenant_id, dataset_id, document_id, segment_id, child_chunk_id):
+        """Update child chunk."""
+        # check dataset
+        dataset_id = str(dataset_id)
+        tenant_id = str(tenant_id)
+        dataset = db.session.query(Dataset).filter(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id).first()
+        if not dataset:
+            raise NotFound("Dataset not found.")
+
+        # check document
+        document_id = str(document_id)
+        document = DocumentService.get_document(dataset.id, document_id)
+        if not document:
+            raise NotFound("Document not found.")
+
+        # check segment
+        segment_id = str(segment_id)
+        segment = DocumentSegment.query.filter(
+            DocumentSegment.id == str(segment_id),
+            DocumentSegment.tenant_id == current_user.current_tenant_id
+        ).first()
+        if not segment:
+            raise NotFound("Segment not found.")
+
+        # check child chunk
+        child_chunk_id = str(child_chunk_id)
+        child_chunk = ChildChunk.query.filter(
+            ChildChunk.id == str(child_chunk_id),
+            ChildChunk.tenant_id == current_user.current_tenant_id
+        ).first()
+        if not child_chunk:
+            raise NotFound("Child chunk not found.")
+
+        # validate args
+        parser = reqparse.RequestParser()
+        parser.add_argument("content", type=str, required=True, nullable=False, location="json")
+        args = parser.parse_args()
+
+        try:
+            child_chunk = SegmentService.update_child_chunk(
+                args.get("content"), child_chunk, segment, document, dataset
+            )
+        except ChildChunkIndexingServiceError as e:
+            raise ChildChunkIndexingError(str(e))
+
+        return {"data": marshal(child_chunk, child_chunk_fields)}, 200
+
+
 api.add_resource(SegmentApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments")
 api.add_resource(
     DatasetSegmentApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>"
 )
+api.add_resource(
+    ChildChunkAddApi,
+    "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks"
+)
+api.add_resource(
+    ChildChunkUpdateApi,
+    "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks/<uuid:child_chunk_id>"
+)
diff --git a/move_section.js b/move_section.js
new file mode 100644
index 0000000000..ac20869fd4
--- /dev/null
+++ b/move_section.js
@@ -0,0 +1 @@
+const fs = require("fs"); const path = require("path"); const filePath = path.join(process.cwd(), "web/app/(commonLayout)/datasets/template/template.zh.mdx"); let content = fs.readFileSync(filePath, "utf8"); const lines = content.split("\n"); const retrievalSection = lines.slice(1234, 1335).join("\n"); content = lines.slice(0, 1234).concat(lines.slice(1335)).join("\n"); content += "\n\n" + retrievalSection; fs.writeFileSync(filePath, content);
diff --git a/web/app/(commonLayout)/datasets/template/template.zh.mdx b/web/app/(commonLayout)/datasets/template/template.zh.mdx
index db72ef9a08..69cf9552b1 100644
--- a/web/app/(commonLayout)/datasets/template/template.zh.mdx
+++ b/web/app/(commonLayout)/datasets/template/template.zh.mdx
@@ -881,182 +881,10 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
 
 <hr className='ml-0 mr-0' />
 
-<Heading
-  url='/datasets/{dataset_id}/documents/{batch}/indexing-status'
-  method='GET'
-  title='获取文档嵌入状态（进度）'
-  name='#indexing_status'
-/>
-<Row>
-  <Col>
-    ### Path
-    <Properties>
-      <Property name='dataset_id' type='string' key='dataset_id'>
-        知识库 ID
-      </Property>
-      <Property name='batch' type='string' key='batch'>
-        上传文档的批次号
-      </Property>
-    </Properties>
-  </Col>
-  <Col sticky>
-    <CodeGroup
-      title="Request"
-      tag="GET"
-      label="/datasets/{dataset_id}/documents/{batch}/indexing-status"
-      targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{batch}/indexing-status' \\\n--header 'Authorization: Bearer {api_key}'`}
-    >
-    ```bash {{ title: 'cURL' }}
-    curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{batch}/indexing-status' \
-    --header 'Authorization: Bearer {api_key}' \
-    ```
-    </CodeGroup>
-    <CodeGroup title="Response">
-    ```json {{ title: 'Response' }}
-    {
-      "data":[{
-        "id": "",
-        "indexing_status": "indexing",
-        "processing_started_at": 1681623462.0,
-        "parsing_completed_at": 1681623462.0,
-        "cleaning_completed_at": 1681623462.0,
-        "splitting_completed_at": 1681623462.0,
-        "completed_at": null,
-        "paused_at": null,
-        "error": null,
-        "stopped_at": null,
-        "completed_segments": 24,
-        "total_segments": 100
-      }]
-    }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
-
-<hr className='ml-0 mr-0' />
-
-<Heading
-  url='/datasets/{dataset_id}/documents/{document_id}'
-  method='DELETE'
-  title='删除文档'
-  name='#delete_document'
-/>
-<Row>
-  <Col>
-    ### Path
-    <Properties>
-      <Property name='dataset_id' type='string' key='dataset_id'>
-        知识库 ID
-      </Property>
-      <Property name='document_id' type='string' key='document_id'>
-        文档 ID
-      </Property>
-    </Properties>
-  </Col>
-  <Col sticky>
-    <CodeGroup
-      title="Request"
-      tag="DELETE"
-      label="/datasets/{dataset_id}/documents/{document_id}"
-      targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}' \\\n--header 'Authorization: Bearer {api_key}'`}
-    >
-    ```bash {{ title: 'cURL' }}
-    curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}' \
-    --header 'Authorization: Bearer {api_key}' \
-    ```
-    </CodeGroup>
-    <CodeGroup title="Response">
-    ```json {{ title: 'Response' }}
-    {
-      "result": "success"
-    }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
-
-<hr className='ml-0 mr-0' />
-
-<Heading
-  url='/datasets/{dataset_id}/documents'
-  method='GET'
-  title='知识库文档列表'
-  name='#dataset_document_list'
-/>
-<Row>
-  <Col>
-    ### Path
-    <Properties>
-      <Property name='dataset_id' type='string' key='dataset_id'>
-        知识库 ID
-      </Property>
-    </Properties>
-
-    ### Query
-    <Properties>
-      <Property name='keyword' type='string' key='keyword'>
-        搜索关键词，可选，目前仅搜索文档名称
-      </Property>
-      <Property name='page' type='string' key='page'>
-        页码，可选
-      </Property>
-      <Property name='limit' type='string' key='limit'>
-        返回条数，可选，默认 20，范围 1-100
-      </Property>
-    </Properties>
-  </Col>
-  <Col sticky>
-    <CodeGroup
-      title="Request"
-      tag="GET"
-      label="/datasets/{dataset_id}/documents"
-      targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents' \\\n--header 'Authorization: Bearer {api_key}'`}
-    >
-    ```bash {{ title: 'cURL' }}
-    curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents' \
-    --header 'Authorization: Bearer {api_key}' \
-    ```
-    </CodeGroup>
-    <CodeGroup title="Response">
-    ```json {{ title: 'Response' }}
-    {
-      "data": [
-        {
-          "id": "",
-          "position": 1,
-          "data_source_type": "file_upload",
-          "data_source_info": null,
-          "dataset_process_rule_id": null,
-          "name": "dify",
-          "created_from": "",
-          "created_by": "",
-          "created_at": 1681623639,
-          "tokens": 0,
-          "indexing_status": "waiting",
-          "error": null,
-          "enabled": true,
-          "disabled_at": null,
-          "disabled_by": null,
-          "archived": false
-        },
-      ],
-      "has_more": false,
-      "limit": 20,
-      "total": 9,
-      "page": 1
-    }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
-
-<hr className='ml-0 mr-0' />
-
 <Heading
   url='/datasets/{dataset_id}/documents/{document_id}/segments'
   method='POST'
-  title='新增分段'
+  title='新增文档分段'
   name='#create_new_segment'
 />
 <Row>
@@ -1351,6 +1179,311 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
   </Col>
 </Row>
 
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'
+  method='POST'
+  title='新增文档子分段'
+  name='#create_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        分段 ID
+      </Property>
+    </Properties>
+
+    ### Request Body
+    <Properties>
+      <Property name='content' type='string' key='content'>
+        子分段内容
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="POST"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
+      targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"content": "子分段内容"}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks' \
+    --header 'Authorization: Bearer {api_key}' \
+    --header 'Content-Type: application/json' \
+    --data-raw '{
+        "content": "子分段内容"
+    }'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": {
+        "id": "",
+        "segment_id": "",
+        "content": "子分段内容",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'
+  method='GET'
+  title='查询文档子分段'
+  name='#get_child_chunks'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        分段 ID
+      </Property>
+    </Properties>
+
+    ### Query
+    <Properties>
+      <Property name='keyword' type='string' key='keyword'>
+        搜索关键词（选填）
+      </Property>
+      <Property name='page' type='integer' key='page'>
+        页码（选填，默认1）
+      </Property>
+      <Property name='limit' type='integer' key='limit'>
+        每页数量（选填，默认20，最大100）
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="GET"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
+      targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks?page=1&limit=20' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks?page=1&limit=20' \
+    --header 'Authorization: Bearer {api_key}'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": [{
+        "id": "",
+        "segment_id": "",
+        "content": "子分段内容",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }],
+      "total": 1,
+      "total_pages": 1,
+      "page": 1,
+      "limit": 20
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'
+  method='DELETE'
+  title='删除文档子分段'
+  name='#delete_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        分段 ID
+      </Property>
+      <Property name='child_chunk_id' type='string' key='child_chunk_id'>
+        子分段 ID
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="DELETE"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}"
+      targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \
+    --header 'Authorization: Bearer {api_key}'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "result": "success"
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Row>
+  <Col>
+    ### 错误信息
+    <Properties>
+      <Property name='code' type='string' key='code'>
+        返回的错误代码
+      </Property>
+    </Properties>
+    <Properties>
+      <Property name='status' type='number' key='status'>
+        返回的错误状态
+      </Property>
+    </Properties>
+    <Properties>
+      <Property name='message' type='string' key='message'>
+        返回的错误信息
+      </Property>
+    </Properties>
+  </Col>
+  <Col>
+    <CodeGroup title="Example">
+    ```json {{ title: 'Response' }}
+      {
+        "code": "no_file_uploaded",
+        "message": "Please upload your file.",
+        "status": 400
+      }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'
+  method='PATCH'
+  title='更新文档子分段'
+  name='#update_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        分段 ID
+      </Property>
+      <Property name='child_chunk_id' type='string' key='child_chunk_id'>
+        子分段 ID
+      </Property>
+    </Properties>
+
+    ### Request Body
+    <Properties>
+      <Property name='content' type='string' key='content'>
+        子分段内容
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="PATCH"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}"
+      targetCode={`curl --location --request PATCH '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"content": "更新的子分段内容"}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request PATCH '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \
+    --header 'Authorization: Bearer {api_key}' \
+    --header 'Content-Type: application/json' \
+    --data-raw '{
+        "content": "更新的子分段内容"
+    }'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": {
+        "id": "",
+        "segment_id": "",
+        "content": "更新的子分段内容",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
 <hr className='ml-0 mr-0' />
 
 <Heading
@@ -1548,39 +1681,7 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
 </Row>
 
 
-<hr className='ml-0 mr-0' />
 
-<Row>
-  <Col>
-    ### 错误信息
-    <Properties>
-      <Property name='code' type='string' key='code'>
-        返回的错误代码
-      </Property>
-    </Properties>
-    <Properties>
-      <Property name='status' type='number' key='status'>
-        返回的错误状态
-      </Property>
-    </Properties>
-    <Properties>
-      <Property name='message' type='string' key='message'>
-        返回的错误信息
-      </Property>
-    </Properties>
-  </Col>
-  <Col>
-    <CodeGroup title="Example">
-    ```json {{ title: 'Response' }}
-      {
-        "code": "no_file_uploaded",
-        "message": "Please upload your file.",
-        "status": 400
-      }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
 <table className="max-w-auto border-collapse border border-slate-400" style={{ maxWidth: 'none', width: 'auto' }}>
   <thead style={{ background: '#f9fafc' }}>
     <tr>
@@ -1652,4 +1753,4 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
     </tr>
   </tbody>
 </table>
-<div className="pb-4" />
+<div className="pb-4" />
\ No newline at end of file

From 9b311f8196d5788bc047ed1e81239d429deb856c Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 13:59:30 +0800
Subject: [PATCH 03/21] feat(api): implement CRUD operations for child chunks
 in dataset API

---
 .../datasets/template/template.en.mdx         | 272 +++++++++++++++++-
 1 file changed, 271 insertions(+), 1 deletion(-)

diff --git a/web/app/(commonLayout)/datasets/template/template.en.mdx b/web/app/(commonLayout)/datasets/template/template.en.mdx
index c276f55a23..a5ceb8105b 100644
--- a/web/app/(commonLayout)/datasets/template/template.en.mdx
+++ b/web/app/(commonLayout)/datasets/template/template.en.mdx
@@ -1347,6 +1347,276 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
 
 <hr className='ml-0 mr-0' />
 
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'
+  method='POST'
+  title='Create Child Chunk'
+  name='#create_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Params
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        Knowledge ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        Document ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        Segment ID
+      </Property>
+    </Properties>
+
+    ### Request Body
+    <Properties>
+      <Property name='content' type='string' key='content'>
+        Child chunk content
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="POST"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
+      targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"content": "Child chunk content"}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks' \
+    --header 'Authorization: Bearer {api_key}' \
+    --header 'Content-Type: application/json' \
+    --data-raw '{
+        "content": "Child chunk content"
+    }'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": {
+        "id": "",
+        "segment_id": "",
+        "content": "Child chunk content",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'
+  method='GET'
+  title='Get Child Chunks'
+  name='#get_child_chunks'
+/>
+<Row>
+  <Col>
+    ### Params
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        Knowledge ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        Document ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        Segment ID
+      </Property>
+    </Properties>
+
+    ### Query
+    <Properties>
+      <Property name='keyword' type='string' key='keyword'>
+        Search keyword (optional)
+      </Property>
+      <Property name='page' type='integer' key='page'>
+        Page number (optional, default: 1)
+      </Property>
+      <Property name='limit' type='integer' key='limit'>
+        Items per page (optional, default: 20, max: 100)
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="GET"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
+      targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks?page=1&limit=20' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks?page=1&limit=20' \
+    --header 'Authorization: Bearer {api_key}'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": [{
+        "id": "",
+        "segment_id": "",
+        "content": "Child chunk content",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }],
+      "total": 1,
+      "total_pages": 1,
+      "page": 1,
+      "limit": 20
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'
+  method='DELETE'
+  title='Delete Child Chunk'
+  name='#delete_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Params
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        Knowledge ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        Document ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        Segment ID
+      </Property>
+      <Property name='child_chunk_id' type='string' key='child_chunk_id'>
+        Child Chunk ID
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="DELETE"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}"
+      targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \
+    --header 'Authorization: Bearer {api_key}'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "result": "success"
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'
+  method='PATCH'
+  title='Update Child Chunk'
+  name='#update_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Params
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        Knowledge ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        Document ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        Segment ID
+      </Property>
+      <Property name='child_chunk_id' type='string' key='child_chunk_id'>
+        Child Chunk ID
+      </Property>
+    </Properties>
+
+    ### Request Body
+    <Properties>
+      <Property name='content' type='string' key='content'>
+        Child chunk content
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="PATCH"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}"
+      targetCode={`curl --location --request PATCH '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"content": "Updated child chunk content"}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request PATCH '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \
+    --header 'Authorization: Bearer {api_key}' \
+    --header 'Content-Type: application/json' \
+    --data-raw '{
+        "content": "Updated child chunk content"
+    }'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": {
+        "id": "",
+        "segment_id": "",
+        "content": "Updated child chunk content",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
 <Heading
   url='/datasets/{dataset_id}/documents/{document_id}/upload-file'
   method='GET'
@@ -1645,4 +1915,4 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
     </tr>
   </tbody>
 </table>
-<div className="pb-4" />
+<div className="pb-4" />
\ No newline at end of file

From dd060746a1240b832279da39eb2c7e37a18c4359 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 14:04:06 +0800
Subject: [PATCH 04/21] chore: remove unused move_section.js file

---
 move_section.js | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 move_section.js

diff --git a/move_section.js b/move_section.js
deleted file mode 100644
index ac20869fd4..0000000000
--- a/move_section.js
+++ /dev/null
@@ -1 +0,0 @@
-const fs = require("fs"); const path = require("path"); const filePath = path.join(process.cwd(), "web/app/(commonLayout)/datasets/template/template.zh.mdx"); let content = fs.readFileSync(filePath, "utf8"); const lines = content.split("\n"); const retrievalSection = lines.slice(1234, 1335).join("\n"); content = lines.slice(0, 1234).concat(lines.slice(1335)).join("\n"); content += "\n\n" + retrievalSection; fs.writeFileSync(filePath, content);

From 84afd643499e6df4fd5d5477a4239cc2756baf3b Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 14:27:40 +0800
Subject: [PATCH 05/21] feat(api): update dataset document endpoints for
 indexing status and management

---
 .../datasets/template/template.zh.mdx         | 513 +++++++-----------
 1 file changed, 206 insertions(+), 307 deletions(-)

diff --git a/web/app/(commonLayout)/datasets/template/template.zh.mdx b/web/app/(commonLayout)/datasets/template/template.zh.mdx
index b5d629f350..8bd3d8d5eb 100644
--- a/web/app/(commonLayout)/datasets/template/template.zh.mdx
+++ b/web/app/(commonLayout)/datasets/template/template.zh.mdx
@@ -881,10 +881,182 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
 
 <hr className='ml-0 mr-0' />
 
+<Heading
+  url='/datasets/{dataset_id}/documents/{batch}/indexing-status'
+  method='GET'
+  title='获取文档嵌入状态（进度）'
+  name='#indexing_status'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='batch' type='string' key='batch'>
+        上传文档的批次号
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="GET"
+      label="/datasets/{dataset_id}/documents/{batch}/indexing-status"
+      targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{batch}/indexing-status' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{batch}/indexing-status' \
+    --header 'Authorization: Bearer {api_key}' \
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data":[{
+        "id": "",
+        "indexing_status": "indexing",
+        "processing_started_at": 1681623462.0,
+        "parsing_completed_at": 1681623462.0,
+        "cleaning_completed_at": 1681623462.0,
+        "splitting_completed_at": 1681623462.0,
+        "completed_at": null,
+        "paused_at": null,
+        "error": null,
+        "stopped_at": null,
+        "completed_segments": 24,
+        "total_segments": 100
+      }]
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}'
+  method='DELETE'
+  title='删除文档'
+  name='#delete_document'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="DELETE"
+      label="/datasets/{dataset_id}/documents/{document_id}"
+      targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}' \
+    --header 'Authorization: Bearer {api_key}' \
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "result": "success"
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents'
+  method='GET'
+  title='知识库文档列表'
+  name='#dataset_document_list'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+    </Properties>
+
+    ### Query
+    <Properties>
+      <Property name='keyword' type='string' key='keyword'>
+        搜索关键词，可选，目前仅搜索文档名称
+      </Property>
+      <Property name='page' type='string' key='page'>
+        页码，可选
+      </Property>
+      <Property name='limit' type='string' key='limit'>
+        返回条数，可选，默认 20，范围 1-100
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="GET"
+      label="/datasets/{dataset_id}/documents"
+      targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents' \
+    --header 'Authorization: Bearer {api_key}' \
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": [
+        {
+          "id": "",
+          "position": 1,
+          "data_source_type": "file_upload",
+          "data_source_info": null,
+          "dataset_process_rule_id": null,
+          "name": "dify",
+          "created_from": "",
+          "created_by": "",
+          "created_at": 1681623639,
+          "tokens": 0,
+          "indexing_status": "waiting",
+          "error": null,
+          "enabled": true,
+          "disabled_at": null,
+          "disabled_by": null,
+          "archived": false
+        },
+      ],
+      "has_more": false,
+      "limit": 20,
+      "total": 9,
+      "page": 1
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
 <Heading
   url='/datasets/{dataset_id}/documents/{document_id}/segments'
   method='POST'
-  title='新增文档分段'
+  title='新增分段'
   name='#create_new_segment'
 />
 <Row>
@@ -1179,311 +1351,6 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
   </Col>
 </Row>
 
-
-<hr className='ml-0 mr-0' />
-
-<Heading
-  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'
-  method='POST'
-  title='新增文档子分段'
-  name='#create_child_chunk'
-/>
-<Row>
-  <Col>
-    ### Path
-    <Properties>
-      <Property name='dataset_id' type='string' key='dataset_id'>
-        知识库 ID
-      </Property>
-      <Property name='document_id' type='string' key='document_id'>
-        文档 ID
-      </Property>
-      <Property name='segment_id' type='string' key='segment_id'>
-        分段 ID
-      </Property>
-    </Properties>
-
-    ### Request Body
-    <Properties>
-      <Property name='content' type='string' key='content'>
-        子分段内容
-      </Property>
-    </Properties>
-  </Col>
-  <Col sticky>
-    <CodeGroup
-      title="Request"
-      tag="POST"
-      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
-      targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"content": "子分段内容"}'`}
-    >
-    ```bash {{ title: 'cURL' }}
-    curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks' \
-    --header 'Authorization: Bearer {api_key}' \
-    --header 'Content-Type: application/json' \
-    --data-raw '{
-        "content": "子分段内容"
-    }'
-    ```
-    </CodeGroup>
-    <CodeGroup title="Response">
-    ```json {{ title: 'Response' }}
-    {
-      "data": {
-        "id": "",
-        "segment_id": "",
-        "content": "子分段内容",
-        "word_count": 25,
-        "tokens": 0,
-        "index_node_id": "",
-        "index_node_hash": "",
-        "status": "completed",
-        "created_by": "",
-        "created_at": 1695312007,
-        "indexing_at": 1695312007,
-        "completed_at": 1695312007,
-        "error": null,
-        "stopped_at": null
-      }
-    }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
-
-<hr className='ml-0 mr-0' />
-
-<Heading
-  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'
-  method='GET'
-  title='查询文档子分段'
-  name='#get_child_chunks'
-/>
-<Row>
-  <Col>
-    ### Path
-    <Properties>
-      <Property name='dataset_id' type='string' key='dataset_id'>
-        知识库 ID
-      </Property>
-      <Property name='document_id' type='string' key='document_id'>
-        文档 ID
-      </Property>
-      <Property name='segment_id' type='string' key='segment_id'>
-        分段 ID
-      </Property>
-    </Properties>
-
-    ### Query
-    <Properties>
-      <Property name='keyword' type='string' key='keyword'>
-        搜索关键词（选填）
-      </Property>
-      <Property name='page' type='integer' key='page'>
-        页码（选填，默认1）
-      </Property>
-      <Property name='limit' type='integer' key='limit'>
-        每页数量（选填，默认20，最大100）
-      </Property>
-    </Properties>
-  </Col>
-  <Col sticky>
-    <CodeGroup
-      title="Request"
-      tag="GET"
-      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
-      targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks?page=1&limit=20' \\\n--header 'Authorization: Bearer {api_key}'`}
-    >
-    ```bash {{ title: 'cURL' }}
-    curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks?page=1&limit=20' \
-    --header 'Authorization: Bearer {api_key}'
-    ```
-    </CodeGroup>
-    <CodeGroup title="Response">
-    ```json {{ title: 'Response' }}
-    {
-      "data": [{
-        "id": "",
-        "segment_id": "",
-        "content": "子分段内容",
-        "word_count": 25,
-        "tokens": 0,
-        "index_node_id": "",
-        "index_node_hash": "",
-        "status": "completed",
-        "created_by": "",
-        "created_at": 1695312007,
-        "indexing_at": 1695312007,
-        "completed_at": 1695312007,
-        "error": null,
-        "stopped_at": null
-      }],
-      "total": 1,
-      "total_pages": 1,
-      "page": 1,
-      "limit": 20
-    }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
-
-<hr className='ml-0 mr-0' />
-
-<Heading
-  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'
-  method='DELETE'
-  title='删除文档子分段'
-  name='#delete_child_chunk'
-/>
-<Row>
-  <Col>
-    ### Path
-    <Properties>
-      <Property name='dataset_id' type='string' key='dataset_id'>
-        知识库 ID
-      </Property>
-      <Property name='document_id' type='string' key='document_id'>
-        文档 ID
-      </Property>
-      <Property name='segment_id' type='string' key='segment_id'>
-        分段 ID
-      </Property>
-      <Property name='child_chunk_id' type='string' key='child_chunk_id'>
-        子分段 ID
-      </Property>
-    </Properties>
-  </Col>
-  <Col sticky>
-    <CodeGroup
-      title="Request"
-      tag="DELETE"
-      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}"
-      targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \\\n--header 'Authorization: Bearer {api_key}'`}
-    >
-    ```bash {{ title: 'cURL' }}
-    curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \
-    --header 'Authorization: Bearer {api_key}'
-    ```
-    </CodeGroup>
-    <CodeGroup title="Response">
-    ```json {{ title: 'Response' }}
-    {
-      "result": "success"
-    }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
-
-<hr className='ml-0 mr-0' />
-
-<Row>
-  <Col>
-    ### 错误信息
-    <Properties>
-      <Property name='code' type='string' key='code'>
-        返回的错误代码
-      </Property>
-    </Properties>
-    <Properties>
-      <Property name='status' type='number' key='status'>
-        返回的错误状态
-      </Property>
-    </Properties>
-    <Properties>
-      <Property name='message' type='string' key='message'>
-        返回的错误信息
-      </Property>
-    </Properties>
-  </Col>
-  <Col>
-    <CodeGroup title="Example">
-    ```json {{ title: 'Response' }}
-      {
-        "code": "no_file_uploaded",
-        "message": "Please upload your file.",
-        "status": 400
-      }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
-
-<hr className='ml-0 mr-0' />
-
-<Heading
-  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'
-  method='PATCH'
-  title='更新文档子分段'
-  name='#update_child_chunk'
-/>
-<Row>
-  <Col>
-    ### Path
-    <Properties>
-      <Property name='dataset_id' type='string' key='dataset_id'>
-        知识库 ID
-      </Property>
-      <Property name='document_id' type='string' key='document_id'>
-        文档 ID
-      </Property>
-      <Property name='segment_id' type='string' key='segment_id'>
-        分段 ID
-      </Property>
-      <Property name='child_chunk_id' type='string' key='child_chunk_id'>
-        子分段 ID
-      </Property>
-    </Properties>
-
-    ### Request Body
-    <Properties>
-      <Property name='content' type='string' key='content'>
-        子分段内容
-      </Property>
-    </Properties>
-  </Col>
-  <Col sticky>
-    <CodeGroup
-      title="Request"
-      tag="PATCH"
-      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}"
-      targetCode={`curl --location --request PATCH '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"content": "更新的子分段内容"}'`}
-    >
-    ```bash {{ title: 'cURL' }}
-    curl --location --request PATCH '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \
-    --header 'Authorization: Bearer {api_key}' \
-    --header 'Content-Type: application/json' \
-    --data-raw '{
-        "content": "更新的子分段内容"
-    }'
-    ```
-    </CodeGroup>
-    <CodeGroup title="Response">
-    ```json {{ title: 'Response' }}
-    {
-      "data": {
-        "id": "",
-        "segment_id": "",
-        "content": "更新的子分段内容",
-        "word_count": 25,
-        "tokens": 0,
-        "index_node_id": "",
-        "index_node_hash": "",
-        "status": "completed",
-        "created_by": "",
-        "created_at": 1695312007,
-        "indexing_at": 1695312007,
-        "completed_at": 1695312007,
-        "error": null,
-        "stopped_at": null
-      }
-    }
-    ```
-    </CodeGroup>
-  </Col>
-</Row>
-
 <hr className='ml-0 mr-0' />
 
 <Heading
@@ -1929,7 +1796,39 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
   </Col>
 </Row>
 
+<hr className='ml-0 mr-0' />
 
+<Row>
+  <Col>
+    ### 错误信息
+    <Properties>
+      <Property name='code' type='string' key='code'>
+        返回的错误代码
+      </Property>
+    </Properties>
+    <Properties>
+      <Property name='status' type='number' key='status'>
+        返回的错误状态
+      </Property>
+    </Properties>
+    <Properties>
+      <Property name='message' type='string' key='message'>
+        返回的错误信息
+      </Property>
+    </Properties>
+  </Col>
+  <Col>
+    <CodeGroup title="Example">
+    ```json {{ title: 'Response' }}
+      {
+        "code": "no_file_uploaded",
+        "message": "Please upload your file.",
+        "status": 400
+      }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
 <table className="max-w-auto border-collapse border border-slate-400" style={{ maxWidth: 'none', width: 'auto' }}>
   <thead style={{ background: '#f9fafc' }}>
     <tr>
@@ -2001,4 +1900,4 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
     </tr>
   </tbody>
 </table>
-<div className="pb-4" />
\ No newline at end of file
+<div className="pb-4" />

From 113aeab2995562a9246dfc34c2fcd6bd830bb307 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 14:29:17 +0800
Subject: [PATCH 06/21] feat(api): add endpoints for managing child chunks in
 dataset documents

---
 .../datasets/template/template.zh.mdx         | 304 ++++++++++++++++++
 1 file changed, 304 insertions(+)

diff --git a/web/app/(commonLayout)/datasets/template/template.zh.mdx b/web/app/(commonLayout)/datasets/template/template.zh.mdx
index 8bd3d8d5eb..4cdfa43400 100644
--- a/web/app/(commonLayout)/datasets/template/template.zh.mdx
+++ b/web/app/(commonLayout)/datasets/template/template.zh.mdx
@@ -1353,6 +1353,310 @@ import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstructi
 
 <hr className='ml-0 mr-0' />
 
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'
+  method='POST'
+  title='新增文档子分段'
+  name='#create_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        分段 ID
+      </Property>
+    </Properties>
+
+    ### Request Body
+    <Properties>
+      <Property name='content' type='string' key='content'>
+        子分段内容
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="POST"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
+      targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"content": "子分段内容"}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks' \
+    --header 'Authorization: Bearer {api_key}' \
+    --header 'Content-Type: application/json' \
+    --data-raw '{
+        "content": "子分段内容"
+    }'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": {
+        "id": "",
+        "segment_id": "",
+        "content": "子分段内容",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'
+  method='GET'
+  title='查询文档子分段'
+  name='#get_child_chunks'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        分段 ID
+      </Property>
+    </Properties>
+
+    ### Query
+    <Properties>
+      <Property name='keyword' type='string' key='keyword'>
+        搜索关键词（选填）
+      </Property>
+      <Property name='page' type='integer' key='page'>
+        页码（选填，默认1）
+      </Property>
+      <Property name='limit' type='integer' key='limit'>
+        每页数量（选填，默认20，最大100）
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="GET"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
+      targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks?page=1&limit=20' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks?page=1&limit=20' \
+    --header 'Authorization: Bearer {api_key}'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": [{
+        "id": "",
+        "segment_id": "",
+        "content": "子分段内容",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }],
+      "total": 1,
+      "total_pages": 1,
+      "page": 1,
+      "limit": 20
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'
+  method='DELETE'
+  title='删除文档子分段'
+  name='#delete_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        分段 ID
+      </Property>
+      <Property name='child_chunk_id' type='string' key='child_chunk_id'>
+        子分段 ID
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="DELETE"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}"
+      targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \\\n--header 'Authorization: Bearer {api_key}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \
+    --header 'Authorization: Bearer {api_key}'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "result": "success"
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Row>
+  <Col>
+    ### 错误信息
+    <Properties>
+      <Property name='code' type='string' key='code'>
+        返回的错误代码
+      </Property>
+    </Properties>
+    <Properties>
+      <Property name='status' type='number' key='status'>
+        返回的错误状态
+      </Property>
+    </Properties>
+    <Properties>
+      <Property name='message' type='string' key='message'>
+        返回的错误信息
+      </Property>
+    </Properties>
+  </Col>
+  <Col>
+    <CodeGroup title="Example">
+    ```json {{ title: 'Response' }}
+      {
+        "code": "no_file_uploaded",
+        "message": "Please upload your file.",
+        "status": 400
+      }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
+<Heading
+  url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'
+  method='PATCH'
+  title='更新文档子分段'
+  name='#update_child_chunk'
+/>
+<Row>
+  <Col>
+    ### Path
+    <Properties>
+      <Property name='dataset_id' type='string' key='dataset_id'>
+        知识库 ID
+      </Property>
+      <Property name='document_id' type='string' key='document_id'>
+        文档 ID
+      </Property>
+      <Property name='segment_id' type='string' key='segment_id'>
+        分段 ID
+      </Property>
+      <Property name='child_chunk_id' type='string' key='child_chunk_id'>
+        子分段 ID
+      </Property>
+    </Properties>
+
+    ### Request Body
+    <Properties>
+      <Property name='content' type='string' key='content'>
+        子分段内容
+      </Property>
+    </Properties>
+  </Col>
+  <Col sticky>
+    <CodeGroup
+      title="Request"
+      tag="PATCH"
+      label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}"
+      targetCode={`curl --location --request PATCH '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"content": "更新的子分段内容"}'`}
+    >
+    ```bash {{ title: 'cURL' }}
+    curl --location --request PATCH '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}' \
+    --header 'Authorization: Bearer {api_key}' \
+    --header 'Content-Type: application/json' \
+    --data-raw '{
+        "content": "更新的子分段内容"
+    }'
+    ```
+    </CodeGroup>
+    <CodeGroup title="Response">
+    ```json {{ title: 'Response' }}
+    {
+      "data": {
+        "id": "",
+        "segment_id": "",
+        "content": "更新的子分段内容",
+        "word_count": 25,
+        "tokens": 0,
+        "index_node_id": "",
+        "index_node_hash": "",
+        "status": "completed",
+        "created_by": "",
+        "created_at": 1695312007,
+        "indexing_at": 1695312007,
+        "completed_at": 1695312007,
+        "error": null,
+        "stopped_at": null
+      }
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+
+<hr className='ml-0 mr-0' />
+
 <Heading
   url='/datasets/{dataset_id}/documents/{document_id}/upload-file'
   method='GET'

From fd785a40b5efde2ca97f56e55702c1811d7a6522 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 15:09:13 +0800
Subject: [PATCH 07/21] refactor: reorder imports in segment.py for improved
 readability

---
 .../service_api/dataset/segment.py            | 43 +++++++++----------
 1 file changed, 20 insertions(+), 23 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index 9cbcb15a7a..66ba520d86 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -13,15 +13,19 @@ from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
 from core.model_manager import ModelManager
 from core.model_runtime.entities.model_entities import ModelType
 from extensions.ext_database import db
-from fields.segment_fields import segment_fields, child_chunk_fields
-from models.dataset import Dataset, DocumentSegment, ChildChunk
+from fields.segment_fields import child_chunk_fields, segment_fields
+from models.dataset import ChildChunk, Dataset, DocumentSegment
 from services.dataset_service import DatasetService, DocumentService, SegmentService
 from services.entities.knowledge_entities.knowledge_entities import SegmentUpdateArgs
 from services.errors.chunk import (
-    ChildChunkDeleteIndexError as ChildChunkDeleteIndexServiceError,
-    ChildChunkIndexingError as ChildChunkIndexingServiceError,
+    ChildChunkDeleteIndexError,
     ChildChunkIndexingError,
-    ChildChunkDeleteIndexError
+)
+from services.errors.chunk import (
+    ChildChunkDeleteIndexError as ChildChunkDeleteIndexServiceError,
+)
+from services.errors.chunk import (
+    ChildChunkIndexingError as ChildChunkIndexingServiceError,
 )
 
 
@@ -203,9 +207,9 @@ class DatasetSegmentApi(DatasetApiResource):
 
 class ChildChunkAddApi(DatasetApiResource):
     """Resource for child chunks."""
-    
+
     @cloud_edition_billing_resource_check("vector_space", "dataset")
-    @cloud_edition_billing_knowledge_limit_check("add_segment", "dataset") 
+    @cloud_edition_billing_knowledge_limit_check("add_segment", "dataset")
     def post(self, tenant_id, dataset_id, document_id, segment_id):
         """Create child chunk."""
         # check dataset
@@ -224,8 +228,7 @@ class ChildChunkAddApi(DatasetApiResource):
         # check segment
         segment_id = str(segment_id)
         segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id), 
-            DocumentSegment.tenant_id == current_user.current_tenant_id
+            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
         ).first()
         if not segment:
             raise NotFound("Segment not found.")
@@ -277,8 +280,7 @@ class ChildChunkAddApi(DatasetApiResource):
         # check segment
         segment_id = str(segment_id)
         segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id),
-            DocumentSegment.tenant_id == current_user.current_tenant_id
+            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
         ).first()
         if not segment:
             raise NotFound("Segment not found.")
@@ -294,7 +296,7 @@ class ChildChunkAddApi(DatasetApiResource):
         keyword = args["keyword"]
 
         child_chunks = SegmentService.get_child_chunks(segment_id, document_id, dataset_id, page, limit, keyword)
-        
+
         return {
             "data": marshal(child_chunks.items, child_chunk_fields),
             "total": child_chunks.total,
@@ -325,8 +327,7 @@ class ChildChunkUpdateApi(DatasetApiResource):
         # check segment
         segment_id = str(segment_id)
         segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id),
-            DocumentSegment.tenant_id == current_user.current_tenant_id
+            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
         ).first()
         if not segment:
             raise NotFound("Segment not found.")
@@ -334,8 +335,7 @@ class ChildChunkUpdateApi(DatasetApiResource):
         # check child chunk
         child_chunk_id = str(child_chunk_id)
         child_chunk = ChildChunk.query.filter(
-            ChildChunk.id == str(child_chunk_id),
-            ChildChunk.tenant_id == current_user.current_tenant_id
+            ChildChunk.id == str(child_chunk_id), ChildChunk.tenant_id == current_user.current_tenant_id
         ).first()
         if not child_chunk:
             raise NotFound("Child chunk not found.")
@@ -366,8 +366,7 @@ class ChildChunkUpdateApi(DatasetApiResource):
         # check segment
         segment_id = str(segment_id)
         segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id),
-            DocumentSegment.tenant_id == current_user.current_tenant_id
+            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
         ).first()
         if not segment:
             raise NotFound("Segment not found.")
@@ -375,8 +374,7 @@ class ChildChunkUpdateApi(DatasetApiResource):
         # check child chunk
         child_chunk_id = str(child_chunk_id)
         child_chunk = ChildChunk.query.filter(
-            ChildChunk.id == str(child_chunk_id),
-            ChildChunk.tenant_id == current_user.current_tenant_id
+            ChildChunk.id == str(child_chunk_id), ChildChunk.tenant_id == current_user.current_tenant_id
         ).first()
         if not child_chunk:
             raise NotFound("Child chunk not found.")
@@ -401,10 +399,9 @@ api.add_resource(
     DatasetSegmentApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>"
 )
 api.add_resource(
-    ChildChunkAddApi,
-    "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks"
+    ChildChunkAddApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks"
 )
 api.add_resource(
     ChildChunkUpdateApi,
-    "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks/<uuid:child_chunk_id>"
+    "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks/<uuid:child_chunk_id>",
 )

From 2a418f618e0e81f4de71c02f1ba410214d80c08b Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 15:57:36 +0800
Subject: [PATCH 08/21] refactor: rename and reorganize child chunk API classes
 for clarity and consistency

---
 api/controllers/service_api/dataset/segment.py | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index 66ba520d86..f959a4aac9 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -16,7 +16,7 @@ from extensions.ext_database import db
 from fields.segment_fields import child_chunk_fields, segment_fields
 from models.dataset import ChildChunk, Dataset, DocumentSegment
 from services.dataset_service import DatasetService, DocumentService, SegmentService
-from services.entities.knowledge_entities.knowledge_entities import SegmentUpdateArgs
+from services.entities.knowledge_entities.knowledge_entities import SegmentUpdateArgs, ChildChunkUpdateArgs
 from services.errors.chunk import (
     ChildChunkDeleteIndexError,
     ChildChunkIndexingError,
@@ -205,7 +205,7 @@ class DatasetSegmentApi(DatasetApiResource):
         return {"data": marshal(segment, segment_fields), "doc_form": document.doc_form}, 200
 
 
-class ChildChunkAddApi(DatasetApiResource):
+class ChildChunkApi (DatasetApiResource):
     """Resource for child chunks."""
 
     @cloud_edition_billing_resource_check("vector_space", "dataset")
@@ -306,7 +306,7 @@ class ChildChunkAddApi(DatasetApiResource):
         }, 200
 
 
-class ChildChunkUpdateApi(DatasetApiResource):
+class DatasetChildChunkApi(DatasetApiResource):
     """Resource for updating child chunks."""
 
     def delete(self, tenant_id, dataset_id, document_id, segment_id, child_chunk_id):
@@ -386,7 +386,11 @@ class ChildChunkUpdateApi(DatasetApiResource):
 
         try:
             child_chunk = SegmentService.update_child_chunk(
-                args.get("content"), child_chunk, segment, document, dataset
+                ChildChunkUpdateArgs(content=args["content"]),
+                child_chunk,
+                segment,
+                document,
+                dataset
             )
         except ChildChunkIndexingServiceError as e:
             raise ChildChunkIndexingError(str(e))
@@ -399,9 +403,9 @@ api.add_resource(
     DatasetSegmentApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>"
 )
 api.add_resource(
-    ChildChunkAddApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks"
+    ChildChunkApi , "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks"
 )
 api.add_resource(
-    ChildChunkUpdateApi,
+    DatasetChildChunkApi,
     "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks/<uuid:child_chunk_id>",
 )

From 3c10b7ceca406c5f24759d071173ece681d484f6 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 16:21:30 +0800
Subject: [PATCH 09/21] refactor: reorder import statements in segment.py for
 improved clarity

---
 api/controllers/service_api/dataset/segment.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index f959a4aac9..9a469bfed4 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -16,7 +16,7 @@ from extensions.ext_database import db
 from fields.segment_fields import child_chunk_fields, segment_fields
 from models.dataset import ChildChunk, Dataset, DocumentSegment
 from services.dataset_service import DatasetService, DocumentService, SegmentService
-from services.entities.knowledge_entities.knowledge_entities import SegmentUpdateArgs, ChildChunkUpdateArgs
+from services.entities.knowledge_entities.knowledge_entities import ChildChunkUpdateArgs, SegmentUpdateArgs
 from services.errors.chunk import (
     ChildChunkDeleteIndexError,
     ChildChunkIndexingError,

From f9bdc9917a563067beac5cbd63ce66e7482ad65c Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 16:49:47 +0800
Subject: [PATCH 10/21] refactor: update SegmentApi to use new get_segments
 method for improved clarity and efficiency

---
 .../service_api/dataset/segment.py            | 20 ++++++-------------
 api/services/dataset_service.py               | 19 ++++++++++++++++++
 2 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index 9a469bfed4..507cff0e56 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -80,7 +80,7 @@ class SegmentApi(DatasetApiResource):
             return {"error": "Segments is required"}, 400
 
     def get(self, tenant_id, dataset_id, document_id):
-        """Create single segment."""
+        """Get segments."""
         # check dataset
         dataset_id = str(dataset_id)
         tenant_id = str(tenant_id)
@@ -114,21 +114,13 @@ class SegmentApi(DatasetApiResource):
         parser.add_argument("keyword", type=str, default=None, location="args")
         args = parser.parse_args()
 
-        status_list = args["status"]
-        keyword = args["keyword"]
-
-        query = DocumentSegment.query.filter(
-            DocumentSegment.document_id == str(document_id), DocumentSegment.tenant_id == current_user.current_tenant_id
+        segments, total = SegmentService.get_segments(
+            document_id=document_id,
+            tenant_id=current_user.current_tenant_id,
+            status_list=args["status"],
+            keyword=args["keyword"]
         )
 
-        if status_list:
-            query = query.filter(DocumentSegment.status.in_(status_list))
-
-        if keyword:
-            query = query.where(DocumentSegment.content.ilike(f"%{keyword}%"))
-
-        total = query.count()
-        segments = query.order_by(DocumentSegment.position).all()
         return {"data": marshal(segments, segment_fields), "doc_form": document.doc_form, "total": total}, 200
 
 
diff --git a/api/services/dataset_service.py b/api/services/dataset_service.py
index 7ce4e4af22..b935505573 100644
--- a/api/services/dataset_service.py
+++ b/api/services/dataset_service.py
@@ -2155,6 +2155,25 @@ class SegmentService:
             query = query.where(ChildChunk.content.ilike(f"%{keyword}%"))
         return query.paginate(page=page, per_page=limit, max_per_page=100, error_out=False)
 
+    @classmethod
+    def get_segments(cls, document_id: str, tenant_id: str, status_list: list = None, keyword: str = None):
+        """Get segments for a document with optional filtering."""
+        query = DocumentSegment.query.filter(
+            DocumentSegment.document_id == document_id,
+            DocumentSegment.tenant_id == tenant_id
+        )
+
+        if status_list:
+            query = query.filter(DocumentSegment.status.in_(status_list))
+
+        if keyword:
+            query = query.filter(DocumentSegment.content.ilike(f"%{keyword}%"))
+
+        segments = query.order_by(DocumentSegment.position.asc()).all()
+        total = len(segments)
+
+        return segments, total
+
 
 class DatasetCollectionBindingService:
     @classmethod

From eb2255444801af74149d472c1080cabe0cb587f9 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 16:50:26 +0800
Subject: [PATCH 11/21] refactor: enhance get_segments method signature for
 improved type hinting and clarity

---
 api/services/dataset_service.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/api/services/dataset_service.py b/api/services/dataset_service.py
index b935505573..2cd5895e2d 100644
--- a/api/services/dataset_service.py
+++ b/api/services/dataset_service.py
@@ -2156,7 +2156,13 @@ class SegmentService:
         return query.paginate(page=page, per_page=limit, max_per_page=100, error_out=False)
 
     @classmethod
-    def get_segments(cls, document_id: str, tenant_id: str, status_list: list = None, keyword: str = None):
+    def get_segments(
+        cls,
+        document_id: str,
+        tenant_id: str,
+        status_list: list[str] | None = None,
+        keyword: str | None = None
+    ):
         """Get segments for a document with optional filtering."""
         query = DocumentSegment.query.filter(
             DocumentSegment.document_id == document_id,

From 820389990716040d73a8e8d5f048e852917245c3 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 17:57:52 +0800
Subject: [PATCH 12/21] refactor: implement update_segment_by_id method for
 segment updates with validation and checks

---
 .../service_api/dataset/segment.py            | 10 ++-
 api/services/dataset_service.py               | 65 ++++++++++++++++++-
 2 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index 507cff0e56..d724d321fe 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -192,9 +192,13 @@ class DatasetSegmentApi(DatasetApiResource):
         parser.add_argument("segment", type=dict, required=False, nullable=True, location="json")
         args = parser.parse_args()
 
-        SegmentService.segment_create_args_validate(args["segment"], document)
-        segment = SegmentService.update_segment(SegmentUpdateArgs(**args["segment"]), segment, document, dataset)
-        return {"data": marshal(segment, segment_fields), "doc_form": document.doc_form}, 200
+        updated_segment = SegmentService.update_segment(
+            SegmentUpdateArgs(**args["segment"]),
+            segment,
+            document,
+            dataset
+        )
+        return {"data": marshal(updated_segment, segment_fields), "doc_form": document.doc_form}, 200
 
 
 class ChildChunkApi (DatasetApiResource):
diff --git a/api/services/dataset_service.py b/api/services/dataset_service.py
index 2cd5895e2d..7d2c590c5b 100644
--- a/api/services/dataset_service.py
+++ b/api/services/dataset_service.py
@@ -14,7 +14,7 @@ from sqlalchemy.orm import Session
 from werkzeug.exceptions import NotFound
 
 from configs import dify_config
-from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
+from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError, ProviderNotInitializeError
 from core.model_manager import ModelManager
 from core.model_runtime.entities.model_entities import ModelType
 from core.plugin.entities.plugin import ModelProviderID
@@ -2180,6 +2180,69 @@ class SegmentService:
 
         return segments, total
 
+    @classmethod
+    def update_segment_by_id(
+        cls,
+        tenant_id: str,
+        dataset_id: str,
+        document_id: str,
+        segment_id: str,
+        segment_data: dict,
+        user_id: str
+    ) -> tuple[DocumentSegment, Document]:
+        """Update a segment by its ID with validation and checks."""
+        # check dataset
+        dataset = db.session.query(Dataset).filter(
+            Dataset.tenant_id == tenant_id,
+            Dataset.id == dataset_id
+        ).first()
+        if not dataset:
+            raise NotFound("Dataset not found.")
+
+        # check user's model setting
+        DatasetService.check_dataset_model_setting(dataset)
+
+        # check document
+        document = DocumentService.get_document(dataset_id, document_id)
+        if not document:
+            raise NotFound("Document not found.")
+
+        # check embedding model setting if high quality
+        if dataset.indexing_technique == "high_quality":
+            try:
+                model_manager = ModelManager()
+                model_manager.get_model_instance(
+                    tenant_id=user_id,
+                    provider=dataset.embedding_model_provider,
+                    model_type=ModelType.TEXT_EMBEDDING,
+                    model=dataset.embedding_model,
+                )
+            except LLMBadRequestError:
+                raise ProviderNotInitializeError(
+                    "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
+                )
+            except ProviderTokenNotInitError as ex:
+                raise ProviderNotInitializeError(ex.description)
+
+        # check segment
+        segment = DocumentSegment.query.filter(
+            DocumentSegment.id == segment_id,
+            DocumentSegment.tenant_id == user_id
+        ).first()
+        if not segment:
+            raise NotFound("Segment not found.")
+
+        # validate and update segment
+        cls.segment_create_args_validate(segment_data, document)
+        updated_segment = cls.update_segment(
+            SegmentUpdateArgs(**segment_data),
+            segment,
+            document,
+            dataset
+        )
+
+        return updated_segment, document
+
 
 class DatasetCollectionBindingService:
     @classmethod

From b496bba3d211900c6a396d9759edb2f35963d3ba Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 17:58:07 +0800
Subject: [PATCH 13/21] refactor: reorder import statements in
 dataset_service.py for improved clarity

---
 api/services/dataset_service.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/services/dataset_service.py b/api/services/dataset_service.py
index 7d2c590c5b..9096a279c3 100644
--- a/api/services/dataset_service.py
+++ b/api/services/dataset_service.py
@@ -14,7 +14,7 @@ from sqlalchemy.orm import Session
 from werkzeug.exceptions import NotFound
 
 from configs import dify_config
-from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError, ProviderNotInitializeError
+from core.errors.error import LLMBadRequestError, ProviderNotInitializeError, ProviderTokenNotInitError
 from core.model_manager import ModelManager
 from core.model_runtime.entities.model_entities import ModelType
 from core.plugin.entities.plugin import ModelProviderID

From bfe5eb94c0552e10934ac400072bd9927c9f2956 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 18:12:46 +0800
Subject: [PATCH 14/21] refactor: replace direct DocumentSegment queries with
 SegmentService.get_segment_by_id for improved code clarity and
 maintainability

---
 .../service_api/dataset/segment.py            | 45 +++++++++++--------
 api/services/dataset_service.py               | 17 +++++--
 2 files changed, 39 insertions(+), 23 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index d724d321fe..e25b08ff8a 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -14,7 +14,7 @@ from core.model_manager import ModelManager
 from core.model_runtime.entities.model_entities import ModelType
 from extensions.ext_database import db
 from fields.segment_fields import child_chunk_fields, segment_fields
-from models.dataset import ChildChunk, Dataset, DocumentSegment
+from models.dataset import ChildChunk, Dataset
 from services.dataset_service import DatasetService, DocumentService, SegmentService
 from services.entities.knowledge_entities.knowledge_entities import ChildChunkUpdateArgs, SegmentUpdateArgs
 from services.errors.chunk import (
@@ -140,9 +140,11 @@ class DatasetSegmentApi(DatasetApiResource):
         if not document:
             raise NotFound("Document not found.")
         # check segment
-        segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
-        ).first()
+        segment_id = str(segment_id)
+        segment = SegmentService.get_segment_by_id(
+            segment_id=segment_id,
+            tenant_id=current_user.current_tenant_id
+        )
         if not segment:
             raise NotFound("Segment not found.")
         SegmentService.delete_segment(segment, document, dataset)
@@ -181,9 +183,10 @@ class DatasetSegmentApi(DatasetApiResource):
                 raise ProviderNotInitializeError(ex.description)
             # check segment
         segment_id = str(segment_id)
-        segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
-        ).first()
+        segment = SegmentService.get_segment_by_id(
+            segment_id=segment_id,
+            tenant_id=current_user.current_tenant_id
+        )
         if not segment:
             raise NotFound("Segment not found.")
 
@@ -223,9 +226,10 @@ class ChildChunkApi (DatasetApiResource):
 
         # check segment
         segment_id = str(segment_id)
-        segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
-        ).first()
+        segment = SegmentService.get_segment_by_id(
+            segment_id=segment_id,
+            tenant_id=current_user.current_tenant_id
+        )
         if not segment:
             raise NotFound("Segment not found.")
 
@@ -275,9 +279,10 @@ class ChildChunkApi (DatasetApiResource):
 
         # check segment
         segment_id = str(segment_id)
-        segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
-        ).first()
+        segment = SegmentService.get_segment_by_id(
+            segment_id=segment_id,
+            tenant_id=current_user.current_tenant_id
+        )
         if not segment:
             raise NotFound("Segment not found.")
 
@@ -322,9 +327,10 @@ class DatasetChildChunkApi(DatasetApiResource):
 
         # check segment
         segment_id = str(segment_id)
-        segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
-        ).first()
+        segment = SegmentService.get_segment_by_id(
+            segment_id=segment_id,
+            tenant_id=current_user.current_tenant_id
+        )
         if not segment:
             raise NotFound("Segment not found.")
 
@@ -361,9 +367,10 @@ class DatasetChildChunkApi(DatasetApiResource):
 
         # check segment
         segment_id = str(segment_id)
-        segment = DocumentSegment.query.filter(
-            DocumentSegment.id == str(segment_id), DocumentSegment.tenant_id == current_user.current_tenant_id
-        ).first()
+        segment = SegmentService.get_segment_by_id(
+            segment_id=segment_id,
+            tenant_id=current_user.current_tenant_id
+        )
         if not segment:
             raise NotFound("Segment not found.")
 
diff --git a/api/services/dataset_service.py b/api/services/dataset_service.py
index 9096a279c3..2a36990e2a 100644
--- a/api/services/dataset_service.py
+++ b/api/services/dataset_service.py
@@ -14,7 +14,7 @@ from sqlalchemy.orm import Session
 from werkzeug.exceptions import NotFound
 
 from configs import dify_config
-from core.errors.error import LLMBadRequestError, ProviderNotInitializeError, ProviderTokenNotInitError
+from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
 from core.model_manager import ModelManager
 from core.model_runtime.entities.model_entities import ModelType
 from core.plugin.entities.plugin import ModelProviderID
@@ -2218,11 +2218,12 @@ class SegmentService:
                     model=dataset.embedding_model,
                 )
             except LLMBadRequestError:
-                raise ProviderNotInitializeError(
-                    "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
+                raise ValueError(
+                    "No Embedding Model available. "
+                    "Please configure a valid provider in the Settings -> Model Provider."
                 )
             except ProviderTokenNotInitError as ex:
-                raise ProviderNotInitializeError(ex.description)
+                raise ValueError(ex.description)
 
         # check segment
         segment = DocumentSegment.query.filter(
@@ -2243,6 +2244,14 @@ class SegmentService:
 
         return updated_segment, document
 
+    @classmethod
+    def get_segment_by_id(cls, segment_id: str, tenant_id: str) -> Optional[DocumentSegment]:
+        """Get a segment by its ID."""
+        return DocumentSegment.query.filter(
+            DocumentSegment.id == segment_id,
+            DocumentSegment.tenant_id == tenant_id
+        ).first()
+
 
 class DatasetCollectionBindingService:
     @classmethod

From b53888a79ed42945f7badf0b86dca988483a6436 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 18:25:23 +0800
Subject: [PATCH 15/21] refactor: replace direct ChildChunk queries with
 SegmentService.get_child_chunk_by_id for improved code clarity and
 maintainability

---
 api/controllers/service_api/dataset/segment.py | 16 +++++++++-------
 api/services/dataset_service.py                |  8 ++++++++
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index e25b08ff8a..19a6700318 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -14,7 +14,7 @@ from core.model_manager import ModelManager
 from core.model_runtime.entities.model_entities import ModelType
 from extensions.ext_database import db
 from fields.segment_fields import child_chunk_fields, segment_fields
-from models.dataset import ChildChunk, Dataset
+from models.dataset import  Dataset
 from services.dataset_service import DatasetService, DocumentService, SegmentService
 from services.entities.knowledge_entities.knowledge_entities import ChildChunkUpdateArgs, SegmentUpdateArgs
 from services.errors.chunk import (
@@ -336,9 +336,10 @@ class DatasetChildChunkApi(DatasetApiResource):
 
         # check child chunk
         child_chunk_id = str(child_chunk_id)
-        child_chunk = ChildChunk.query.filter(
-            ChildChunk.id == str(child_chunk_id), ChildChunk.tenant_id == current_user.current_tenant_id
-        ).first()
+        child_chunk = SegmentService.get_child_chunk_by_id(
+            child_chunk_id=child_chunk_id,
+            tenant_id=current_user.current_tenant_id
+        )
         if not child_chunk:
             raise NotFound("Child chunk not found.")
 
@@ -376,9 +377,10 @@ class DatasetChildChunkApi(DatasetApiResource):
 
         # check child chunk
         child_chunk_id = str(child_chunk_id)
-        child_chunk = ChildChunk.query.filter(
-            ChildChunk.id == str(child_chunk_id), ChildChunk.tenant_id == current_user.current_tenant_id
-        ).first()
+        child_chunk = SegmentService.get_child_chunk_by_id(
+            child_chunk_id=child_chunk_id,
+            tenant_id=current_user.current_tenant_id
+        )
         if not child_chunk:
             raise NotFound("Child chunk not found.")
 
diff --git a/api/services/dataset_service.py b/api/services/dataset_service.py
index 2a36990e2a..261aedce8a 100644
--- a/api/services/dataset_service.py
+++ b/api/services/dataset_service.py
@@ -2155,6 +2155,14 @@ class SegmentService:
             query = query.where(ChildChunk.content.ilike(f"%{keyword}%"))
         return query.paginate(page=page, per_page=limit, max_per_page=100, error_out=False)
 
+    @classmethod
+    def get_child_chunk_by_id(cls, child_chunk_id: str, tenant_id: str) -> Optional[ChildChunk]:
+        """Get a child chunk by its ID."""
+        return ChildChunk.query.filter(
+            ChildChunk.id == child_chunk_id,
+            ChildChunk.tenant_id == tenant_id
+        ).first()
+
     @classmethod
     def get_segments(
         cls,

From e146f1a08d5dce88a1d9be13cc14795773bab69a Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 18:25:31 +0800
Subject: [PATCH 16/21] refactor: remove extra space in import statement for
 improved consistency

---
 api/controllers/service_api/dataset/segment.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index 19a6700318..ebed99a1f5 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -14,7 +14,7 @@ from core.model_manager import ModelManager
 from core.model_runtime.entities.model_entities import ModelType
 from extensions.ext_database import db
 from fields.segment_fields import child_chunk_fields, segment_fields
-from models.dataset import  Dataset
+from models.dataset import Dataset
 from services.dataset_service import DatasetService, DocumentService, SegmentService
 from services.entities.knowledge_entities.knowledge_entities import ChildChunkUpdateArgs, SegmentUpdateArgs
 from services.errors.chunk import (

From 3bfc24860a9a40c949f95b1866c74c8b3a337a94 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 19:03:23 +0800
Subject: [PATCH 17/21] refactor: simplify document, segment, and child chunk
 retrieval in DatasetChildChunkApi for improved clarity

---
 api/controllers/service_api/dataset/segment.py | 18 ++++++------------
 1 file changed, 6 insertions(+), 12 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index ebed99a1f5..d094510348 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -360,14 +360,12 @@ class DatasetChildChunkApi(DatasetApiResource):
         if not dataset:
             raise NotFound("Dataset not found.")
 
-        # check document
-        document_id = str(document_id)
-        document = DocumentService.get_document(dataset.id, document_id)
+        # get document
+        document = DocumentService.get_document(dataset_id, document_id)
         if not document:
             raise NotFound("Document not found.")
 
-        # check segment
-        segment_id = str(segment_id)
+        # get segment
         segment = SegmentService.get_segment_by_id(
             segment_id=segment_id,
             tenant_id=current_user.current_tenant_id
@@ -375,8 +373,7 @@ class DatasetChildChunkApi(DatasetApiResource):
         if not segment:
             raise NotFound("Segment not found.")
 
-        # check child chunk
-        child_chunk_id = str(child_chunk_id)
+        # get child chunk
         child_chunk = SegmentService.get_child_chunk_by_id(
             child_chunk_id=child_chunk_id,
             tenant_id=current_user.current_tenant_id
@@ -391,12 +388,9 @@ class DatasetChildChunkApi(DatasetApiResource):
 
         try:
             child_chunk = SegmentService.update_child_chunk(
-                ChildChunkUpdateArgs(content=args["content"]),
-                child_chunk,
-                segment,
-                document,
-                dataset
+                args.get("content"), child_chunk, segment, document, dataset
             )
+
         except ChildChunkIndexingServiceError as e:
             raise ChildChunkIndexingError(str(e))
 

From 13b2aabf90c92e049888afb68287be59f6255608 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 19:03:34 +0800
Subject: [PATCH 18/21] refactor: remove unused ChildChunkUpdateArgs import for
 improved clarity

---
 api/controllers/service_api/dataset/segment.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index d094510348..770fb5be3a 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -16,7 +16,7 @@ from extensions.ext_database import db
 from fields.segment_fields import child_chunk_fields, segment_fields
 from models.dataset import Dataset
 from services.dataset_service import DatasetService, DocumentService, SegmentService
-from services.entities.knowledge_entities.knowledge_entities import ChildChunkUpdateArgs, SegmentUpdateArgs
+from services.entities.knowledge_entities.knowledge_entities import SegmentUpdateArgs
 from services.errors.chunk import (
     ChildChunkDeleteIndexError,
     ChildChunkIndexingError,

From 632476ce296d249984d74f5549232aca1d7c0624 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 19:07:25 +0800
Subject: [PATCH 19/21] refactor: format query for dataset retrieval in
 DatasetChildChunkApi for improved readability

---
 api/controllers/service_api/dataset/segment.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index 770fb5be3a..5ee4165311 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -356,7 +356,9 @@ class DatasetChildChunkApi(DatasetApiResource):
         # check dataset
         dataset_id = str(dataset_id)
         tenant_id = str(tenant_id)
-        dataset = db.session.query(Dataset).filter(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id).first()
+        dataset = db.session.query(Dataset).filter(
+            Dataset.tenant_id == tenant_id, Dataset.id == dataset_id
+        ).first()
         if not dataset:
             raise NotFound("Dataset not found.")
 
@@ -390,7 +392,6 @@ class DatasetChildChunkApi(DatasetApiResource):
             child_chunk = SegmentService.update_child_chunk(
                 args.get("content"), child_chunk, segment, document, dataset
             )
-
         except ChildChunkIndexingServiceError as e:
             raise ChildChunkIndexingError(str(e))
 

From 5539cb3bab3671ec22fe560b3278357407f40ae5 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 19:08:28 +0800
Subject: [PATCH 20/21] refactor: streamline method calls and formatting in
 segment.py and dataset_service.py for improved readability and consistency

---
 .../service_api/dataset/segment.py            | 51 +++++--------------
 api/services/dataset_service.py               | 43 ++++------------
 2 files changed, 22 insertions(+), 72 deletions(-)

diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py
index 5ee4165311..233cd37df4 100644
--- a/api/controllers/service_api/dataset/segment.py
+++ b/api/controllers/service_api/dataset/segment.py
@@ -118,7 +118,7 @@ class SegmentApi(DatasetApiResource):
             document_id=document_id,
             tenant_id=current_user.current_tenant_id,
             status_list=args["status"],
-            keyword=args["keyword"]
+            keyword=args["keyword"],
         )
 
         return {"data": marshal(segments, segment_fields), "doc_form": document.doc_form, "total": total}, 200
@@ -141,10 +141,7 @@ class DatasetSegmentApi(DatasetApiResource):
             raise NotFound("Document not found.")
         # check segment
         segment_id = str(segment_id)
-        segment = SegmentService.get_segment_by_id(
-            segment_id=segment_id,
-            tenant_id=current_user.current_tenant_id
-        )
+        segment = SegmentService.get_segment_by_id(segment_id=segment_id, tenant_id=current_user.current_tenant_id)
         if not segment:
             raise NotFound("Segment not found.")
         SegmentService.delete_segment(segment, document, dataset)
@@ -183,10 +180,7 @@ class DatasetSegmentApi(DatasetApiResource):
                 raise ProviderNotInitializeError(ex.description)
             # check segment
         segment_id = str(segment_id)
-        segment = SegmentService.get_segment_by_id(
-            segment_id=segment_id,
-            tenant_id=current_user.current_tenant_id
-        )
+        segment = SegmentService.get_segment_by_id(segment_id=segment_id, tenant_id=current_user.current_tenant_id)
         if not segment:
             raise NotFound("Segment not found.")
 
@@ -196,15 +190,12 @@ class DatasetSegmentApi(DatasetApiResource):
         args = parser.parse_args()
 
         updated_segment = SegmentService.update_segment(
-            SegmentUpdateArgs(**args["segment"]),
-            segment,
-            document,
-            dataset
+            SegmentUpdateArgs(**args["segment"]), segment, document, dataset
         )
         return {"data": marshal(updated_segment, segment_fields), "doc_form": document.doc_form}, 200
 
 
-class ChildChunkApi (DatasetApiResource):
+class ChildChunkApi(DatasetApiResource):
     """Resource for child chunks."""
 
     @cloud_edition_billing_resource_check("vector_space", "dataset")
@@ -226,10 +217,7 @@ class ChildChunkApi (DatasetApiResource):
 
         # check segment
         segment_id = str(segment_id)
-        segment = SegmentService.get_segment_by_id(
-            segment_id=segment_id,
-            tenant_id=current_user.current_tenant_id
-        )
+        segment = SegmentService.get_segment_by_id(segment_id=segment_id, tenant_id=current_user.current_tenant_id)
         if not segment:
             raise NotFound("Segment not found.")
 
@@ -279,10 +267,7 @@ class ChildChunkApi (DatasetApiResource):
 
         # check segment
         segment_id = str(segment_id)
-        segment = SegmentService.get_segment_by_id(
-            segment_id=segment_id,
-            tenant_id=current_user.current_tenant_id
-        )
+        segment = SegmentService.get_segment_by_id(segment_id=segment_id, tenant_id=current_user.current_tenant_id)
         if not segment:
             raise NotFound("Segment not found.")
 
@@ -327,18 +312,14 @@ class DatasetChildChunkApi(DatasetApiResource):
 
         # check segment
         segment_id = str(segment_id)
-        segment = SegmentService.get_segment_by_id(
-            segment_id=segment_id,
-            tenant_id=current_user.current_tenant_id
-        )
+        segment = SegmentService.get_segment_by_id(segment_id=segment_id, tenant_id=current_user.current_tenant_id)
         if not segment:
             raise NotFound("Segment not found.")
 
         # check child chunk
         child_chunk_id = str(child_chunk_id)
         child_chunk = SegmentService.get_child_chunk_by_id(
-            child_chunk_id=child_chunk_id,
-            tenant_id=current_user.current_tenant_id
+            child_chunk_id=child_chunk_id, tenant_id=current_user.current_tenant_id
         )
         if not child_chunk:
             raise NotFound("Child chunk not found.")
@@ -356,9 +337,7 @@ class DatasetChildChunkApi(DatasetApiResource):
         # check dataset
         dataset_id = str(dataset_id)
         tenant_id = str(tenant_id)
-        dataset = db.session.query(Dataset).filter(
-            Dataset.tenant_id == tenant_id, Dataset.id == dataset_id
-        ).first()
+        dataset = db.session.query(Dataset).filter(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id).first()
         if not dataset:
             raise NotFound("Dataset not found.")
 
@@ -368,17 +347,13 @@ class DatasetChildChunkApi(DatasetApiResource):
             raise NotFound("Document not found.")
 
         # get segment
-        segment = SegmentService.get_segment_by_id(
-            segment_id=segment_id,
-            tenant_id=current_user.current_tenant_id
-        )
+        segment = SegmentService.get_segment_by_id(segment_id=segment_id, tenant_id=current_user.current_tenant_id)
         if not segment:
             raise NotFound("Segment not found.")
 
         # get child chunk
         child_chunk = SegmentService.get_child_chunk_by_id(
-            child_chunk_id=child_chunk_id,
-            tenant_id=current_user.current_tenant_id
+            child_chunk_id=child_chunk_id, tenant_id=current_user.current_tenant_id
         )
         if not child_chunk:
             raise NotFound("Child chunk not found.")
@@ -403,7 +378,7 @@ api.add_resource(
     DatasetSegmentApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>"
 )
 api.add_resource(
-    ChildChunkApi , "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks"
+    ChildChunkApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks"
 )
 api.add_resource(
     DatasetChildChunkApi,
diff --git a/api/services/dataset_service.py b/api/services/dataset_service.py
index 261aedce8a..e956849af5 100644
--- a/api/services/dataset_service.py
+++ b/api/services/dataset_service.py
@@ -2158,23 +2158,15 @@ class SegmentService:
     @classmethod
     def get_child_chunk_by_id(cls, child_chunk_id: str, tenant_id: str) -> Optional[ChildChunk]:
         """Get a child chunk by its ID."""
-        return ChildChunk.query.filter(
-            ChildChunk.id == child_chunk_id,
-            ChildChunk.tenant_id == tenant_id
-        ).first()
+        return ChildChunk.query.filter(ChildChunk.id == child_chunk_id, ChildChunk.tenant_id == tenant_id).first()
 
     @classmethod
     def get_segments(
-        cls,
-        document_id: str,
-        tenant_id: str,
-        status_list: list[str] | None = None,
-        keyword: str | None = None
+        cls, document_id: str, tenant_id: str, status_list: list[str] | None = None, keyword: str | None = None
     ):
         """Get segments for a document with optional filtering."""
         query = DocumentSegment.query.filter(
-            DocumentSegment.document_id == document_id,
-            DocumentSegment.tenant_id == tenant_id
+            DocumentSegment.document_id == document_id, DocumentSegment.tenant_id == tenant_id
         )
 
         if status_list:
@@ -2190,20 +2182,11 @@ class SegmentService:
 
     @classmethod
     def update_segment_by_id(
-        cls,
-        tenant_id: str,
-        dataset_id: str,
-        document_id: str,
-        segment_id: str,
-        segment_data: dict,
-        user_id: str
+        cls, tenant_id: str, dataset_id: str, document_id: str, segment_id: str, segment_data: dict, user_id: str
     ) -> tuple[DocumentSegment, Document]:
         """Update a segment by its ID with validation and checks."""
         # check dataset
-        dataset = db.session.query(Dataset).filter(
-            Dataset.tenant_id == tenant_id,
-            Dataset.id == dataset_id
-        ).first()
+        dataset = db.session.query(Dataset).filter(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id).first()
         if not dataset:
             raise NotFound("Dataset not found.")
 
@@ -2227,28 +2210,21 @@ class SegmentService:
                 )
             except LLMBadRequestError:
                 raise ValueError(
-                    "No Embedding Model available. "
-                    "Please configure a valid provider in the Settings -> Model Provider."
+                    "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
                 )
             except ProviderTokenNotInitError as ex:
                 raise ValueError(ex.description)
 
         # check segment
         segment = DocumentSegment.query.filter(
-            DocumentSegment.id == segment_id,
-            DocumentSegment.tenant_id == user_id
+            DocumentSegment.id == segment_id, DocumentSegment.tenant_id == user_id
         ).first()
         if not segment:
             raise NotFound("Segment not found.")
 
         # validate and update segment
         cls.segment_create_args_validate(segment_data, document)
-        updated_segment = cls.update_segment(
-            SegmentUpdateArgs(**segment_data),
-            segment,
-            document,
-            dataset
-        )
+        updated_segment = cls.update_segment(SegmentUpdateArgs(**segment_data), segment, document, dataset)
 
         return updated_segment, document
 
@@ -2256,8 +2232,7 @@ class SegmentService:
     def get_segment_by_id(cls, segment_id: str, tenant_id: str) -> Optional[DocumentSegment]:
         """Get a segment by its ID."""
         return DocumentSegment.query.filter(
-            DocumentSegment.id == segment_id,
-            DocumentSegment.tenant_id == tenant_id
+            DocumentSegment.id == segment_id, DocumentSegment.tenant_id == tenant_id
         ).first()
 
 

From faed90724086edc1abef5d8c1548d7c31ae9a6b4 Mon Sep 17 00:00:00 2001
From: ZeroZ_JQ <ballmanjq@gmail.com>
Date: Tue, 18 Mar 2025 19:24:44 +0800
Subject: [PATCH 21/21] refactor: ensure return type consistency in
 get_child_chunk_by_id and get_segment_by_id methods in SegmentService

---
 api/services/dataset_service.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/api/services/dataset_service.py b/api/services/dataset_service.py
index e956849af5..b852ff8f0b 100644
--- a/api/services/dataset_service.py
+++ b/api/services/dataset_service.py
@@ -2158,7 +2158,8 @@ class SegmentService:
     @classmethod
     def get_child_chunk_by_id(cls, child_chunk_id: str, tenant_id: str) -> Optional[ChildChunk]:
         """Get a child chunk by its ID."""
-        return ChildChunk.query.filter(ChildChunk.id == child_chunk_id, ChildChunk.tenant_id == tenant_id).first()
+        result = ChildChunk.query.filter(ChildChunk.id == child_chunk_id, ChildChunk.tenant_id == tenant_id).first()
+        return result if isinstance(result, ChildChunk) else None
 
     @classmethod
     def get_segments(
@@ -2231,9 +2232,10 @@ class SegmentService:
     @classmethod
     def get_segment_by_id(cls, segment_id: str, tenant_id: str) -> Optional[DocumentSegment]:
         """Get a segment by its ID."""
-        return DocumentSegment.query.filter(
+        result = DocumentSegment.query.filter(
             DocumentSegment.id == segment_id, DocumentSegment.tenant_id == tenant_id
         ).first()
+        return result if isinstance(result, DocumentSegment) else None
 
 
 class DatasetCollectionBindingService: