feat: enhance document handling in hit test results to include source file IDs and update related tests

Author: liuruibin

apps/knowledge/README.md

@@ -91,3 +91,5 @@ the external vision model or tool runs in the worker.
 召回测试 `/hit_test` 的每条分段结果包含 `document_resource_type`，取自所属文档的 `resource_type`：
 `image` 表示图片文档，`document` 表示普通文档。工作空间、系统资源管理和系统共享资源的召回测试
 使用相同字段；此字段与命中向量类型无关，普通文档中的插图命中仍返回 `document`。
+图片文档的结果额外包含 `document_image_id`，取自文档的 `meta.source_file_id`，用于通过现有文件接口显示原图。
+该字段不依赖命中的是文本还是图片向量；普通文档以及缺少原文件引用的图片文档返回 `null`。

apps/knowledge/serializers/knowledge.py

@@ -1448,18 +1448,20 @@ def hit_test(self):
                 str(paragraph.get("id")): paragraph
                 for paragraph in list_paragraph([hit.get("paragraph_id") for hit in hit_list])
             }
-            document_resource_type_map = {
-                str(document_id): resource_type
-                for document_id, resource_type in QuerySet(Document)
+            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")
+                .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")
@@ -1468,9 +1470,10 @@ def hit_test(self):
                 result_list.append(
                     {
                         **paragraph,
-                        "document_resource_type": document_resource_type_map.get(
-                            str(paragraph.get("document_id")), DocumentResourceType.DOCUMENT
-                        ),
+                        "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/tests/retrieval/test_vector_metadata.py

@@ -112,6 +112,7 @@ def test_hit_test_decodes_sql_metadata_and_preserves_image_description_hit_type(
                 {
                     **paragraph,
                     "document_resource_type": DocumentResourceType.DOCUMENT,
+                    "document_image_id": None,
                     "similarity": 0.9,
                     "comprehensive_score": 0.95,
                     "source_id": asset_id,
@@ -137,15 +138,18 @@ def test_hit_test_reports_document_origin_independently_of_vector_type(
         knowledge_query.filter.return_value.exists.return_value = True
         document_query = MagicMock()
         query_set.side_effect = {Knowledge: knowledge_query, Document: document_query}.get
+        image_file_id = "00000000-0000-0000-0000-000000000010"
         document_query.filter.return_value.values_list.return_value = [
-            ("image-document", DocumentResourceType.IMAGE),
-            ("ordinary-document", DocumentResourceType.DOCUMENT),
+            ("image-document", DocumentResourceType.IMAGE, image_file_id),
+            ("ordinary-document", DocumentResourceType.DOCUMENT, "00000000-0000-0000-0000-000000000011"),
+            ("image-without-file", DocumentResourceType.IMAGE, None),
         ]
         paragraphs = [
             {"id": "image-text", "document_id": "image-document"},
             {"id": "image-vector", "document_id": "image-document"},
             {"id": "ordinary-text", "document_id": "ordinary-document"},
             {"id": "ordinary-image", "document_id": "ordinary-document"},
+            {"id": "image-without-file", "document_id": "image-without-file"},
         ]
         list_paragraph.return_value = paragraphs
         get_vector.return_value.hit_test.return_value = [
@@ -156,8 +160,8 @@ def test_hit_test_reports_document_origin_independently_of_vector_type(
             }
             for paragraph, source_type, unit_type in zip(
                 paragraphs,
-                [SourceType.PARAGRAPH, SourceType.IMAGE, SourceType.PARAGRAPH, SourceType.IMAGE],
-                ["text", "image", "text", "image"],
+                [SourceType.PARAGRAPH, SourceType.IMAGE, SourceType.PARAGRAPH, SourceType.IMAGE, SourceType.PARAGRAPH],
+                ["text", "image", "text", "image", "text"],
             )
         ]
 
@@ -179,7 +183,12 @@ def test_hit_test_reports_document_origin_independently_of_vector_type(
                 DocumentResourceType.IMAGE,
                 DocumentResourceType.DOCUMENT,
                 DocumentResourceType.DOCUMENT,
+                DocumentResourceType.IMAGE,
             ],
         )
-        self.assertEqual([row["hit_unit_type"] for row in result], ["text", "image", "text", "image"])
-        document_query.filter.return_value.values_list.assert_called_once_with("id", "resource_type")
+        self.assertEqual([row["hit_unit_type"] for row in result], ["text", "image", "text", "image", "text"])
+        self.assertEqual([row["document_image_id"] for row in result], [image_file_id, image_file_id, None, None, None])
+        self.assertTrue(all("source_file_id" not in row and "image_id" not in row for row in result))
+        document_query.filter.return_value.values_list.assert_called_once_with(
+            "id", "resource_type", "meta__source_file_id"
+        )