Abnormal image path in knowledge base retrieval results

[chenchaolong0]

Self Checks

• This is only for bug report, if you would like to ask a question, please head to Discussions.
• I have searched for existing issues search for existing issues, including closed ones.
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，谢谢！:）
• Please do not modify this template :) and fill in all the required fields.

Steps to reproduce

1.Store images in the knowledge base
2.Intelligent search retrieves the image path from the knowledge base for rendering
3.Abnormal image path prevents rendering

✔️ Expected Behavior

No response

❌ Actual Behavior

[tiven-w]

@code-xpertai Let's analyze this problem (without coding yet).

[ponyfly6]

@xpert-ai 你先分析一下这个issue，使用中文

[code-xpertai]

问题分析

问题描述

知识库检索结果中的图片路径异常，导致图片无法正常渲染。

根本原因

经过代码分析，发现问题出在 KnowledgeDocument 实体的 fileUrl 字段未能正确填充。

1. 数据流分析

文件上传流程：

• 文件上传后存储在 StorageFile 表中
• StorageFileSubscriber.afterLoad() 会自动将 fileUrl 填充为完整 URL（通过 provider.url(entity.file)）

知识库文档创建流程：

• KnowledgeDocument 实体有 storageFileId 关联到 StorageFile
• 但 KnowledgeDocumentSubscriber 只处理文档计数，没有在加载时自动填充 fileUrl

知识库检索流程：

• KnowledgeSearchQueryHandler.similaritySearchWithScore() 查询 chunks 时会关联 document 并选择 fileUrl
• DocumentChunkDTO 包含 document: DocumentSimpleDTO，其中暴露了 fileUrl
• 前端 knowledges.component.html 使用 item.document?.fileUrl 显示链接

2. 问题定位

查看 document.service.ts 的 createDocument 方法：

async createDocument(document: Partial<IKnowledgeDocument>): Promise<KnowledgeDocument> {
  if (!document.type) {
    if (document.storageFileId) {
      const storageFile = await this.storageFileService.findOne(document.storageFileId)
      const fileType = storageFile.originalName.split('.').pop()
      document.type = fileType
      // ❌ 没有设置 document.fileUrl = storageFile.fileUrl
    }
    ...
  }
}

当通过 storageFileId 创建文档时，只设置了 type，没有将 storageFile.fileUrl 复制到 document.fileUrl。

3. 影响范围

• 通过本地上传的文件创建的知识库文档
• 通过 local-file 源策略加载的文档（local-files.strategy.ts 中正确设置了 metadata.fileUrl）
• 检索结果中需要显示原始文件链接的场景

解决方案

方案一：在 KnowledgeDocumentSubscriber 中添加 afterLoad 钩子（推荐）

在 packages/server-ai/src/knowledge-document/document.subscriber.ts 中添加：

async afterLoad(entity: KnowledgeDocument, event?: LoadEvent<KnowledgeDocument>): Promise<void> {
  if (entity instanceof KnowledgeDocument && entity.storageFileId && !entity.fileUrl) {
    const storageFile = await event.manager.findOne(StorageFile, { 
      where: { id: entity.storageFileId } 
    })
    if (storageFile?.fileUrl) {
      entity.fileUrl = storageFile.fileUrl
    }
  }
}

方案二：在 createDocument 方法中设置 fileUrl

在 document.service.ts 的 createDocument 方法中：

if (document.storageFileId) {
  const storageFile = await this.storageFileService.findOne(document.storageFileId)
  document.type = storageFile.originalName.split('.').pop()
  document.fileUrl ??= storageFile.fileUrl  // 添加这行
}

推荐方案

推荐方案一，原因：

1. 与 StorageFileSubscriber 的处理方式一致
2. 能处理历史数据（已存在但 fileUrl 为空的文档）
3. 不影响现有创建逻辑

需要修改的文件

1. packages/server-ai/src/knowledge-document/document.subscriber.ts - 添加 afterLoad 方法

验证步骤

1. 上传文件到知识库
2. 执行知识库检索
3. 检查返回结果中 document.fileUrl 是否为完整 URL
4. 前端能正常渲染图片链接

---

请确认此分析是否正确，确认后我将开始实施修复。

[ponyfly6]

@xpert-ai 确认，开分支，修复，提pr

[code-xpertai]

✅ Fix Implemented

PR #479 has been created to fix this issue: #479

Problem Summary

When knowledge base documents are created from uploaded files, the fileUrl field was not being populated, causing images to fail rendering in knowledge base search results.

Root Cause

The KnowledgeDocumentSubscriber.afterLoad hook had issues:

1. Used deprecated findOneBy method
2. Incorrectly tried to access storageFile.fileUrl which doesn't exist on the StorageFile entity (the fileUrl is computed dynamically by StorageFileSubscriber)

Solution

Updated the afterLoad hook to:

1. Use findOne with proper where clause and select to fetch only needed fields (id, file, storageProvider)
2. Compute fileUrl directly using FileStorage API (same approach as StorageFileSubscriber)

Files Changed

• packages/server-ai/src/knowledge-document/document.subscriber.ts

This fix ensures that when a KnowledgeDocument entity is loaded, if it has a storageFileId but no fileUrl, the subscriber will compute the correct URL from the storage provider.