fix: improve knowledge base upload error messages (AstrBotDevs#7534)

* fix: improve knowledge base upload error messages

* fix: deduplicate knowledge base upload logs

* fix: handle type errors in kb embedding validation

Author: catDforD

astrbot/core/db/vec_db/faiss_impl/vec_db.py

@@ -4,6 +4,7 @@
 import numpy as np
 
 from astrbot import logger
+from astrbot.core.exceptions import KnowledgeBaseUploadError
 from astrbot.core.provider.provider import EmbeddingProvider, RerankProvider
 
 from ..base import BaseVecDB, Result
@@ -80,6 +81,32 @@ async def insert_batch(
             )
             return []
 
+        content_count = len(contents)
+        if len(metadatas) != content_count:
+            raise KnowledgeBaseUploadError(
+                stage="storage",
+                user_message=(
+                    f"存储失败：文本分块数量与元数据数量不一致（期望 {content_count}，"
+                    f"实际 {len(metadatas)}）。"
+                ),
+                details={
+                    "expected_contents": content_count,
+                    "actual_metadatas": len(metadatas),
+                },
+            )
+        if len(ids) != content_count:
+            raise KnowledgeBaseUploadError(
+                stage="storage",
+                user_message=(
+                    f"存储失败：文本分块数量与文档 ID 数量不一致（期望 {content_count}，"
+                    f"实际 {len(ids)}）。"
+                ),
+                details={
+                    "expected_contents": content_count,
+                    "actual_ids": len(ids),
+                },
+            )
+
         start = time.time()
         logger.debug(f"Generating embeddings for {len(contents)} contents...")
         vectors = await self.embedding_provider.get_embeddings_batch(
@@ -93,16 +120,73 @@ async def insert_batch(
         logger.debug(
             f"Generated embeddings for {len(contents)} contents in {end - start:.2f} seconds.",
         )
+        if len(vectors) != content_count:
+            raise KnowledgeBaseUploadError(
+                stage="embedding",
+                user_message=(
+                    "向量化失败：嵌入模型返回的向量数量与文本分块数量不一致"
+                    f"（期望 {content_count}，实际 {len(vectors)}）。"
+                    "这通常说明当前 Embedding 接口未完整返回批量结果，"
+                    "或该服务不兼容当前批量请求格式。"
+                ),
+                details={
+                    "expected_contents": content_count,
+                    "actual_vectors": len(vectors),
+                },
+            )
 
         # 使用 DocumentStorage 的批量插入方法
         int_ids = await self.document_storage.insert_documents_batch(
             ids,
             contents,
             metadatas,
         )
+        if len(int_ids) != content_count:
+            raise KnowledgeBaseUploadError(
+                stage="storage",
+                user_message=(
+                    f"存储失败：写入文档索引后返回的内部 ID 数量与文本分块数量不一致"
+                    f"（期望 {content_count}，实际 {len(int_ids)}）。"
+                ),
+                details={
+                    "expected_contents": content_count,
+                    "actual_int_ids": len(int_ids),
+                },
+            )
 
         # 批量插入向量到 FAISS
-        vectors_array = np.array(vectors).astype("float32")
+        try:
+            vectors_array = np.asarray(vectors, dtype=np.float32)
+        except (TypeError, ValueError) as exc:
+            raise KnowledgeBaseUploadError(
+                stage="embedding",
+                user_message=(
+                    "向量化失败：嵌入模型返回的向量格式不正确，"
+                    "无法转换为统一的浮点向量矩阵。"
+                ),
+                details={"vector_count": len(vectors)},
+            ) from exc
+        if vectors_array.ndim != 2:
+            raise KnowledgeBaseUploadError(
+                stage="embedding",
+                user_message=(
+                    "向量化失败：嵌入模型返回的向量格式不正确，无法构造成二维向量矩阵。"
+                ),
+                details={"actual_ndim": int(vectors_array.ndim)},
+            )
+        if vectors_array.shape[1] != self.embedding_storage.dimension:
+            raise KnowledgeBaseUploadError(
+                stage="embedding",
+                user_message=(
+                    "向量化失败：返回向量维度与当前知识库索引维度不一致"
+                    f"（期望 {self.embedding_storage.dimension}，"
+                    f"实际 {vectors_array.shape[1]}）。"
+                ),
+                details={
+                    "expected_dimension": self.embedding_storage.dimension,
+                    "actual_dimension": int(vectors_array.shape[1]),
+                },
+            )
         await self.embedding_storage.insert_batch(vectors_array, int_ids)
         return int_ids
 

astrbot/core/exceptions.py

@@ -11,3 +11,22 @@ class ProviderNotFoundError(AstrBotError):
 
 class EmptyModelOutputError(AstrBotError):
     """Raised when the model response contains no usable assistant output."""
+
+
+class KnowledgeBaseUploadError(AstrBotError):
+    """Raised when knowledge base upload fails with a user-facing message."""
+
+    def __init__(
+        self,
+        *,
+        stage: str,
+        user_message: str,
+        details: dict | None = None,
+    ) -> None:
+        super().__init__(user_message)
+        self.stage = stage
+        self.user_message = user_message
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        return self.user_message

astrbot/core/knowledge_base/kb_helper.py

@@ -10,6 +10,7 @@
 
 from astrbot.core import logger
 from astrbot.core.db.vec_db.base import BaseVecDB
+from astrbot.core.exceptions import KnowledgeBaseUploadError
 from astrbot.core.provider.manager import ProviderManager
 from astrbot.core.provider.provider import (
     EmbeddingProvider,
@@ -264,10 +265,31 @@ async def upload_document(
                 if progress_callback:
                     await progress_callback("parsing", 0, 100)
 
-                parser = await select_parser(f".{file_type}")
-                parse_result = await parser.parse(file_content, file_name)
+                try:
+                    parser = await select_parser(f".{file_type}")
+                    parse_result = await parser.parse(file_content, file_name)
+                except KnowledgeBaseUploadError:
+                    raise
+                except Exception as exc:
+                    raise KnowledgeBaseUploadError(
+                        stage="parsing",
+                        user_message=(
+                            "文档解析失败：无法读取或解析上传文件。"
+                            "请确认文件格式受支持且文件内容未损坏。"
+                        ),
+                        details={"file_name": file_name},
+                    ) from exc
                 text_content = parse_result.text
                 media_items = parse_result.media
+                if not text_content or not text_content.strip():
+                    raise KnowledgeBaseUploadError(
+                        stage="parsing",
+                        user_message=(
+                            "文档解析失败：未能从文件中提取可索引文本。"
+                            "该文件可能是扫描件、纯图片 PDF，或格式暂不受支持。"
+                        ),
+                        details={"file_name": file_name},
+                    )
 
                 if progress_callback:
                     await progress_callback("parsing", 100, 100)
@@ -288,11 +310,31 @@ async def upload_document(
                 if progress_callback:
                     await progress_callback("chunking", 0, 100)
 
-                chunks_text = await self.chunker.chunk(
-                    text_content,
-                    chunk_size=chunk_size,
-                    chunk_overlap=chunk_overlap,
+                try:
+                    chunks_text = await self.chunker.chunk(
+                        text_content,
+                        chunk_size=chunk_size,
+                        chunk_overlap=chunk_overlap,
+                    )
+                except KnowledgeBaseUploadError:
+                    raise
+                except Exception as exc:
+                    raise KnowledgeBaseUploadError(
+                        stage="chunking",
+                        user_message=(
+                            "分块失败：文档内容在切分文本块时发生错误。"
+                            "请稍后重试，或调整分块参数后再次上传。"
+                        ),
+                        details={"file_name": file_name},
+                    ) from exc
+
+            if not chunks_text or not any(chunk.strip() for chunk in chunks_text):
+                raise KnowledgeBaseUploadError(
+                    stage="chunking",
+                    user_message=("分块失败：文档内容为空，未生成任何可索引文本块。"),
+                    details={"file_name": file_name},
                 )
+
             contents = []
             metadatas = []
             for idx, chunk_text in enumerate(chunks_text):
@@ -313,14 +355,23 @@ async def embedding_progress_callback(current, total) -> None:
                 if progress_callback:
                     await progress_callback("embedding", current, total)
 
-            await self.vec_db.insert_batch(
-                contents=contents,
-                metadatas=metadatas,
-                batch_size=batch_size,
-                tasks_limit=tasks_limit,
-                max_retries=max_retries,
-                progress_callback=embedding_progress_callback,
-            )
+            try:
+                await self.vec_db.insert_batch(
+                    contents=contents,
+                    metadatas=metadatas,
+                    batch_size=batch_size,
+                    tasks_limit=tasks_limit,
+                    max_retries=max_retries,
+                    progress_callback=embedding_progress_callback,
+                )
+            except KnowledgeBaseUploadError:
+                raise
+            except Exception as exc:
+                raise KnowledgeBaseUploadError(
+                    stage="storage",
+                    user_message=("存储失败：文本块已生成，但写入知识库索引时出错。"),
+                    details={"file_name": file_name},
+                ) from exc
 
             # 保存文档的元数据
             doc = KBDocument(
@@ -334,22 +385,47 @@ async def embedding_progress_callback(current, total) -> None:
                 chunk_count=len(chunks_text),
                 media_count=0,
             )
-            async with self.kb_db.get_db() as session:
-                async with session.begin():
-                    session.add(doc)
-                    for media in saved_media:
-                        session.add(media)
-                    await session.commit()
-
-                await session.refresh(doc)
+            try:
+                async with self.kb_db.get_db() as session:
+                    async with session.begin():
+                        session.add(doc)
+                        for media in saved_media:
+                            session.add(media)
+                        await session.commit()
+
+                    await session.refresh(doc)
+            except KnowledgeBaseUploadError:
+                raise
+            except Exception as exc:
+                raise KnowledgeBaseUploadError(
+                    stage="metadata",
+                    user_message=(
+                        "元数据保存失败：文本块已写入知识库，但文档记录保存失败。"
+                    ),
+                    details={"file_name": file_name, "doc_id": doc_id},
+                ) from exc
 
             vec_db: FaissVecDB = self.vec_db  # type: ignore
-            await self.kb_db.update_kb_stats(kb_id=self.kb.kb_id, vec_db=vec_db)
-            await self.refresh_kb()
-            await self.refresh_document(doc_id)
+            try:
+                await self.kb_db.update_kb_stats(kb_id=self.kb.kb_id, vec_db=vec_db)
+                await self.refresh_kb()
+                await self.refresh_document(doc_id)
+            except KnowledgeBaseUploadError:
+                raise
+            except Exception as exc:
+                raise KnowledgeBaseUploadError(
+                    stage="metadata",
+                    user_message=(
+                        "元数据更新失败：文档已上传，但知识库统计信息刷新失败。"
+                    ),
+                    details={"file_name": file_name, "doc_id": doc_id},
+                ) from exc
             return doc
         except Exception as e:
-            logger.error(f"上传文档失败: {e}")
+            if isinstance(e, KnowledgeBaseUploadError):
+                logger.warning(f"上传文档失败: {e}")
+            else:
+                logger.error(f"上传文档失败: {e}", exc_info=True)
             # if file_path.exists():
             #     file_path.unlink()
 
@@ -360,7 +436,7 @@ async def embedding_progress_callback(current, total) -> None:
                 except Exception as me:
                     logger.warning(f"清理多媒体文件失败 {media_path}: {me}")
 
-            raise e
+            raise
 
     async def list_documents(
         self,

astrbot/dashboard/routes/knowledge_base.py

@@ -128,6 +128,13 @@ async def _callback(stage: str, current: int, total: int) -> None:
 
         return _callback
 
+    @staticmethod
+    def _format_failed_doc_error(file_name: str, error: Exception) -> str:
+        message = str(error).strip() or "上传失败：发生未知错误。"
+        if message.startswith(file_name):
+            return message
+        return f"{file_name}: {message}"
+
     async def _background_upload_task(
         self,
         task_id: str,
@@ -189,7 +196,12 @@ async def _background_upload_task(
                 except Exception as e:
                     logger.error(f"上传文档 {file_info['file_name']} 失败: {e}")
                     failed_docs.append(
-                        {"file_name": file_info["file_name"], "error": str(e)},
+                        {
+                            "file_name": file_info["file_name"],
+                            "error": self._format_failed_doc_error(
+                                file_info["file_name"], e
+                            ),
+                        },
                     )
 
             # 更新任务完成状态
@@ -276,7 +288,10 @@ async def _background_import_task(
                 except Exception as e:
                     logger.error(f"导入文档 {file_name} 失败: {e}")
                     failed_docs.append(
-                        {"file_name": file_name, "error": str(e)},
+                        {
+                            "file_name": file_name,
+                            "error": self._format_failed_doc_error(file_name, e),
+                        },
                     )
 
             # 更新任务完成状态