feat: enrich paragraph sources with document metadata and update related tests

Author: liuruibin

apps/application/serializers/application_chat_record.py

@@ -25,12 +25,13 @@
 from common.utils.common import post
 from django.db import transaction
 from django.db.models import QuerySet
-from django.db.models.aggregates import Max, Min
+from django.db.models.aggregates import Max
 from django.utils.translation import gettext
 from django.utils.translation import gettext_lazy as _
 from knowledge.models import Document, Knowledge, Paragraph, Problem, ProblemParagraphMapping
 from knowledge.serializers.common import get_embedding_model_id_by_knowledge_id, update_document_char_length
 from knowledge.serializers.paragraph import ParagraphSerializers
+from knowledge.services.multimodal_retrieval import enrich_paragraph_sources
 from knowledge.task.embedding import embedding_by_paragraph, embedding_by_paragraph_list
 from rest_framework import serializers
 from rest_framework.utils.formatting import lazy_format
@@ -188,6 +189,8 @@ def reset_chat_record(chat_record, show_source, show_exec):
                     if "document_id" in (rl.get("metadata") or {}) and "knowledge_id" in (rl.get("metadata") or {})
                 ]
         paragraph_list = list({p.get("id"): p for p in paragraph_list}.values())
+        if show_source:
+            paragraph_list = enrich_paragraph_sources(paragraph_list)
         knowledge_list = knowledge_list + [
             {"id": knowledge_id, **knowledge}
             for knowledge_id, knowledge in reduce(

apps/application/tests/test_chat_record_sources.py

@@ -0,0 +1,57 @@
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from django.test import SimpleTestCase
+
+from application.serializers.application_chat_record import ApplicationChatRecordQuerySerializers
+from knowledge.models import DocumentResourceType, KnowledgeType
+
+
+class ChatRecordSourceTests(SimpleTestCase):
+    def setUp(self):
+        self.paragraph = {"id": "paragraph-1", "document_id": "document-1", "knowledge_id": "knowledge-1"}
+        self.record = SimpleNamespace(
+            details={
+                "search": {"type": "search-knowledge-node", "show_knowledge": True, "paragraph_list": [self.paragraph]}
+            },
+            improve_paragraph_id_list=[],
+        )
+        serializer = patch("application.serializers.application_chat_record.ChatRecordSerializerModel")
+        serializer.start().return_value.data = {}
+        self.addCleanup(serializer.stop)
+
+    @patch("knowledge.services.multimodal_retrieval.QuerySet")
+    def test_legacy_chat_sources_include_document_metadata_without_changing_snapshot(self, query_set):
+        query_set.return_value.filter.return_value.values_list.return_value = [
+            ("document-1", KnowledgeType.WORKFLOW, DocumentResourceType.IMAGE, "original-image-file")
+        ]
+
+        result = ApplicationChatRecordQuerySerializers.reset_chat_record(self.record, True, False)
+
+        self.assertEqual(result["paragraph_list"][0]["knowledge_type"], KnowledgeType.WORKFLOW)
+        self.assertEqual(result["paragraph_list"][0]["document_resource_type"], DocumentResourceType.IMAGE)
+        self.assertEqual(result["paragraph_list"][0]["document_image_id"], "original-image-file")
+        self.assertEqual(result["knowledge_list"][0]["knowledge_type"], KnowledgeType.WORKFLOW)
+        self.assertNotIn("document_image_id", self.paragraph)
+
+    @patch("knowledge.services.multimodal_retrieval.QuerySet")
+    def test_hidden_sources_do_not_load_metadata(self, query_set):
+        result = ApplicationChatRecordQuerySerializers.reset_chat_record(self.record, False, False)
+
+        self.assertNotIn("paragraph_list", result)
+        query_set.assert_not_called()
+
+    @patch("knowledge.services.multimodal_retrieval.QuerySet")
+    def test_reranker_sources_include_metadata(self, query_set):
+        self.record.details = {
+            "rerank": {"type": "reranker-node", "show_knowledge": True, "result_list": [{"metadata": self.paragraph}]}
+        }
+        query_set.return_value.filter.return_value.values_list.return_value = [
+            ("document-1", KnowledgeType.LARK, DocumentResourceType.DOCUMENT, "ordinary-file")
+        ]
+
+        result = ApplicationChatRecordQuerySerializers.reset_chat_record(self.record, True, False)
+
+        self.assertEqual(result["paragraph_list"][0]["knowledge_type"], KnowledgeType.LARK)
+        self.assertEqual(result["paragraph_list"][0]["document_resource_type"], DocumentResourceType.DOCUMENT)
+        self.assertIsNone(result["paragraph_list"][0]["document_image_id"])

apps/application/tests/test_workflow_nodes.py

@@ -8,10 +8,12 @@
 from application.workflow.nodes.data_source_web_node.data_source_web_node import DataSourceWebNode
 from application.workflow.nodes.search_knowledge_node.search_knowledge_node import (
     _get_recalled_image_list,
+    _list_paragraph,
     _record_recalled_items,
     _reset_paragraph,
 )
-from knowledge.models import SourceType
+from knowledge.models import Document, DocumentResourceType, Knowledge, KnowledgeType, SourceType
+from application.workflow.nodes.search_document_node.search_document_node import SearchDocumentNode
 from common.utils.fork import ChildLink, Fork
 
 
@@ -26,6 +28,21 @@ def test_failed_web_fetch_fails_workflow_instead_of_returning_an_empty_snapshot(
 
 
 class SearchKnowledgeNodeTests(SimpleTestCase):
+    @patch("knowledge.services.multimodal_retrieval.QuerySet")
+    @patch("application.workflow.nodes.search_knowledge_node.search_knowledge_node.native_search")
+    def test_workflow_paragraph_query_includes_source_fields(self, native_search, query_set):
+        paragraph_id = "00000000-0000-0000-0000-000000000001"
+        native_search.return_value = [{"id": paragraph_id, "document_id": "image-document"}]
+        query_set.return_value.filter.return_value.values_list.return_value = [
+            ("image-document", KnowledgeType.BASE, DocumentResourceType.IMAGE, "original-image-file")
+        ]
+
+        result = _list_paragraph([{"paragraph_id": paragraph_id}], MagicMock())
+
+        self.assertEqual(result[0]["knowledge_type"], KnowledgeType.BASE)
+        self.assertEqual(result[0]["document_resource_type"], DocumentResourceType.IMAGE)
+        self.assertEqual(result[0]["document_image_id"], "original-image-file")
+
     def test_image_hit_metadata_is_attached_to_recalled_paragraph(self):
         paragraph_id = "00000000-0000-0000-0000-000000000001"
         asset_id = "00000000-0000-0000-0000-000000000002"
@@ -40,6 +57,9 @@ def test_image_hit_metadata_is_attached_to_recalled_paragraph(self):
             "update_time": created_at,
             "create_time": created_at,
             "meta": {},
+            "knowledge_type": KnowledgeType.BASE,
+            "document_resource_type": DocumentResourceType.IMAGE,
+            "document_image_id": file_id,
         }
         embedding = {
             "paragraph_id": paragraph_id,
@@ -57,6 +77,9 @@ def test_image_hit_metadata_is_attached_to_recalled_paragraph(self):
         self.assertEqual(result["hit_unit_type"], "image")
         self.assertEqual(result["hit_asset"], asset)
         self.assertEqual(result["comprehensive_score"], 0.93)
+        self.assertEqual(result["knowledge_type"], KnowledgeType.BASE)
+        self.assertEqual(result["document_resource_type"], DocumentResourceType.IMAGE)
+        self.assertEqual(result["document_image_id"], file_id)
         self.assertEqual(_get_recalled_image_list([result, result]), [asset])
 
     def test_image_text_hit_adds_visual_text_to_retrieval_context(self):
@@ -117,6 +140,48 @@ def test_does_not_record_recall_in_debug_mode(self, record_recall):
         record_recall.assert_not_called()
 
 
+class SearchDocumentNodeSourceTests(SimpleTestCase):
+    @patch(
+        "application.workflow.nodes.search_document_node.search_document_node.filter_workflow_knowledge",
+        return_value=["knowledge-1"],
+    )
+    @patch(
+        "application.workflow.nodes.search_document_node.search_document_node.filter_authorized_ids",
+        return_value=["knowledge-1"],
+    )
+    @patch("application.workflow.nodes.search_document_node.search_document_node.QuerySet")
+    def test_document_search_returns_source_fields_using_current_knowledge_type(
+        self, query_set, _authorized, _workflow
+    ):
+        documents = MagicMock()
+        knowledge = MagicMock()
+        query_set.side_effect = {Document: documents, Knowledge: knowledge}.get
+        documents.filter.return_value.values_list.return_value.__iter__.return_value = iter(["document-1"])
+        documents.filter.return_value.values_list.return_value.distinct.return_value = ["knowledge-1"]
+        documents.filter.return_value.values.return_value = [
+            {
+                "id": "document-1",
+                "knowledge_id": "knowledge-1",
+                "type": KnowledgeType.BASE,
+                "resource_type": DocumentResourceType.IMAGE,
+                "meta": {"source_file_id": "original-image-file"},
+            }
+        ]
+        knowledge.filter.return_value.values.return_value = [{"id": "knowledge-1", "type": KnowledgeType.WEB}]
+        node = SearchDocumentNode.__new__(SearchDocumentNode)
+        node.get_parameters = MagicMock(return_value={"knowledge_id_list": ["knowledge-1"], "search_mode": "custom"})
+        node.get_workflow_parameters = MagicMock(return_value={"workspace_id": "default"})
+        node.workflow_manage = MagicMock()
+        node.write_context = MagicMock()
+
+        node.execute()
+
+        output = next(call.args[1] for call in node.write_context.call_args_list if call.args[0] == "document_items")
+        self.assertEqual(output[0]["knowledge_type"], KnowledgeType.WEB)
+        self.assertEqual(output[0]["document_resource_type"], DocumentResourceType.IMAGE)
+        self.assertEqual(output[0]["document_image_id"], "original-image-file")
+
+
 class AIChatKnowledgeImageTests(SimpleTestCase):
     def setUp(self):
         search_node = SimpleNamespace(id="search", type="search-knowledge-node")

apps/application/workflow/nodes/search_document_node/search_document_node.py

@@ -15,6 +15,7 @@
 from application.workflow.i_node import INode
 from common.utils.shared_resource_auth import filter_authorized_ids
 from knowledge.models import Document, DocumentTag, Knowledge
+from knowledge.services.multimodal_retrieval import get_retrieval_source_metadata
 from knowledge.services.retrieval_access import filter_workflow_knowledge
 
 
@@ -246,6 +247,18 @@ def execute(self):
         final_document_ids = [str(doc["id"]) for doc in document_items]
         final_knowledge_ids = list(set(str(doc["knowledge_id"]) for doc in document_items))
         knowledge_items = list(QuerySet(Knowledge).filter(id__in=final_knowledge_ids).values())
+        knowledge_types = {str(knowledge["id"]): knowledge["type"] for knowledge in knowledge_items}
+        document_items = [
+            {
+                **document,
+                **get_retrieval_source_metadata(
+                    knowledge_types.get(str(document["knowledge_id"])),
+                    document["resource_type"],
+                    (document.get("meta") or {}).get("source_file_id"),
+                ),
+            }
+            for document in document_items
+        ]
 
         self.write_context("document_list", final_document_ids)
         self.write_context("document_items", _serialize_items(document_items))

apps/application/workflow/nodes/search_knowledge_node/search_knowledge_node.py

@@ -24,7 +24,7 @@
 from common.utils.common import flat_map, get_file_content
 from common.utils.shared_resource_auth import filter_authorized_ids
 from knowledge.models import Document, Paragraph, Knowledge, SearchMode, SourceType
-from knowledge.services.multimodal_retrieval import get_hit_asset_map
+from knowledge.services.multimodal_retrieval import enrich_paragraph_sources, get_hit_asset_map
 from knowledge.services.retrieval_stats import get_recall_tracker, record_recall_safely
 from knowledge.services.retrieval_access import filter_workflow_knowledge
 from maxkb.conf import PROJECT_DIR
@@ -202,7 +202,7 @@ def _list_paragraph(embedding_list: List, vector, knowledge_ids=None, document_i
         for paragraph_id in paragraph_id_list:
             if paragraph_id not in exist_paragraph_list:
                 vector.delete_by_paragraph_id(paragraph_id)
-    return paragraph_list
+    return enrich_paragraph_sources(paragraph_list)
 
 
 class SearchKnowledgeNode(INode):

apps/knowledge/EXTERNAL_RETRIEVAL.md

@@ -48,6 +48,9 @@ curl "$BASE_URL/chat/api/v3/knowledge/$KNOWLEDGE_ID/retrieve" \
 similarity 为 0–1（默认 0），search_mode 支持 embedding、keywords、blend（默认 embedding）。
 检索限定当前知识库，返回 `knowledge_id` 和 `hits`，命中包含段落正文（最多 8000 字符）、
 分数、来源与 `citation`（知识库、文档、段落 ID 和名称）；不生成回答。
+每个命中同时包含 `knowledge_type`（KnowledgeType 数字枚举）、`document_resource_type`（`image` 或 `document`）
+和 `document_image_id`。图片文档的 `document_image_id` 为文档原图文件 ID，普通文档或缺少原图引用时为 `null`；
+这些字段与命中向量类型独立，REST 与 MCP 返回相同结果结构。
 过滤跨库、停用或失效段落，仅对实际返回命中累计原有召回统计。正文中的附件沿用现有文件访问规则。
 
 请求体最大 64 KiB。400 为参数错误、401 为缺少/无效凭据、403 为无权限/不允许的 Origin、

apps/knowledge/README.md

@@ -93,3 +93,11 @@ the external vision model or tool runs in the worker.
 使用相同字段；此字段与命中向量类型无关，普通文档中的插图命中仍返回 `document`。
 图片文档的结果额外包含 `document_image_id`，取自文档的 `meta.source_file_id`，用于通过现有文件接口显示原图。
 该字段不依赖命中的是文本还是图片向量；普通文档以及缺少原文件引用的图片文档返回 `null`。
+每条结果同时返回所属知识库当前的 `knowledge_type`，沿用 `KnowledgeType` 数字枚举：
+`0` 通用、`1` Web 站点、`2` 飞书、`3` 语雀、`4` 工作流。
+
+上述三个来源字段也适用于问题关联段落、工作流知识库检索的 `paragraph_list`、
+文档检索节点的 `document_items`、聊天记录查询的来源 `paragraph_list`，以及 REST/MCP 外部检索的 `hits`。
+知识库类型取自所属知识库，图片 ID 取自所属文档的原图引用，与命中向量或普通文档内的插图无关。
+段落来源通过一次批量查询补齐；已包含完整来源字段的聊天快照直接复用，旧快照缺少字段时在读取时补齐，
+不修改已保存的聊天记录。隐藏来源时不加载这些元数据。文档已删除时保留快照中的已知字段，缺少的图片 ID 为 `null`。

apps/knowledge/serializers/common.py

@@ -29,12 +29,13 @@
 from common.utils.common import get_file_content
 from common.utils.fork import Fork
 from common.utils.logger import maxkb_logger
-from knowledge.models import Document, DocumentResourceType, KnowledgeWorkflow, KnowledgeWorkflowVersion, KnowledgeType
+from knowledge.models import Document, DocumentResourceType, KnowledgeWorkflow, KnowledgeType
 from knowledge.models import Paragraph, Problem, ProblemParagraphMapping, Knowledge, File
 from knowledge.serializers.document_strategy import DocumentStrategySerializer
+from knowledge.services.multimodal_retrieval import enrich_paragraph_sources
 from maxkb.conf import PROJECT_DIR
 from models_provider.tools import get_model, get_model_default_params
-from system_manage.models.resource_mapping import ResourceMapping, ResourceType
+from system_manage.models.resource_mapping import ResourceType
 
 
 class MetaSerializer(serializers.Serializer):
@@ -242,9 +243,11 @@ def update_document_char_length(document_id: str):
 def list_paragraph(paragraph_list: List[str]):
     if paragraph_list is None or len(paragraph_list) == 0:
         return []
-    return native_search(
-        QuerySet(Paragraph).filter(id__in=paragraph_list),
-        get_file_content(os.path.join(PROJECT_DIR, "apps", "knowledge", "sql", "list_paragraph.sql")),
+    return enrich_paragraph_sources(
+        native_search(
+            QuerySet(Paragraph).filter(id__in=paragraph_list),
+            get_file_content(os.path.join(PROJECT_DIR, "apps", "knowledge", "sql", "list_paragraph.sql")),
+        )
     )
 
 

apps/knowledge/serializers/knowledge.py

@@ -46,7 +46,6 @@
 
 from knowledge.models import (
     Document,
-    DocumentResourceType,
     DocumentTag,
     File,
     FileSourceType,
@@ -1448,20 +1447,12 @@ def hit_test(self):
                 str(paragraph.get("id")): paragraph
                 for paragraph in list_paragraph([hit.get("paragraph_id") for hit in hit_list])
             }
-            document_map = {
-                str(document_id): {"resource_type": resource_type, "source_file_id": source_file_id}
-                for document_id, resource_type, source_file_id in QuerySet(Document)
-                .filter(id__in={paragraph.get("document_id") for paragraph in paragraph_dict.values()})
-                .values_list("id", "resource_type", "meta__source_file_id")
-            }
             hit_asset_map = get_hit_asset_map(hit_list)
             result_list = []
             for hit in hit_list:
                 paragraph = paragraph_dict.get(str(hit.get("paragraph_id")))
                 if paragraph is None:
                     continue
-                document = document_map.get(str(paragraph.get("document_id")), {})
-                document_resource_type = document.get("resource_type", DocumentResourceType.DOCUMENT)
                 current_hit = hit
                 source_id = current_hit.get("source_id")
                 source_type = current_hit.get("source_type")
@@ -1470,10 +1461,6 @@ def hit_test(self):
                 result_list.append(
                     {
                         **paragraph,
-                        "document_resource_type": document_resource_type,
-                        "document_image_id": document.get("source_file_id")
-                        if document_resource_type == DocumentResourceType.IMAGE
-                        else None,
                         "similarity": current_hit.get("similarity"),
                         "comprehensive_score": current_hit.get("comprehensive_score"),
                         "source_id": source_id,

apps/knowledge/serializers/problem.py

@@ -13,6 +13,7 @@
 from common.utils.common import get_file_content
 from knowledge.models import Problem, ProblemParagraphMapping, Paragraph, Knowledge, SourceType
 from knowledge.serializers.common import get_embedding_model_id_by_knowledge_id
+from knowledge.services.multimodal_retrieval import enrich_paragraph_sources
 from knowledge.task.embedding import delete_embedding_by_source_ids, update_problem_embedding, embedding_by_data_list
 from maxkb.const import PROJECT_DIR
 
@@ -175,14 +176,16 @@ def list_paragraph(self, with_valid=True):
             )
             if problem_paragraph_mapping is None or len(problem_paragraph_mapping) == 0:
                 return []
-            return native_search(
-                QuerySet(Paragraph).filter(
-                    knowledge_id=self.data.get("knowledge_id"),
-                    id__in=[row.paragraph_id for row in problem_paragraph_mapping],
-                ),
-                select_string=get_file_content(
-                    os.path.join(PROJECT_DIR, "apps", "knowledge", "sql", "list_paragraph.sql")
-                ),
+            return enrich_paragraph_sources(
+                native_search(
+                    QuerySet(Paragraph).filter(
+                        knowledge_id=self.data.get("knowledge_id"),
+                        id__in=[row.paragraph_id for row in problem_paragraph_mapping],
+                    ),
+                    select_string=get_file_content(
+                        os.path.join(PROJECT_DIR, "apps", "knowledge", "sql", "list_paragraph.sql")
+                    ),
+                )
             )
 
         def one(self, with_valid=True):