fix: 改进知识库的初始化错误处理 (#7243)

* fix: 改进 KnowledgeBaseManager 和 KBHelper 中的初始化错误处理

* fix: 改进知识库初始化和重排序错误处理，增强日志记录

* fix: 改进知识库模块初始化和检索错误处理

* fix(ui): handle kb init errors in list cards

display a dedicated error state for knowledge base cards that fail
initialization, including a visible badge and error details

prevent navigation and edit actions for failed cards while keeping
delete available, and hide normal stats/description for error items

add list.initError locale strings for en-US, ru-RU, and zh-CN

* fix(kb): avoid replacing helper on init failure

Initialize a new KB helper before swapping instances so a failed re-init
does not break the active knowledge base service.

If initialization fails, restore in-memory KB settings and keep the
existing helper and previous init error state.

Also clear stale init_error after successful vector DB initialization to
prevent outdated error reporting.

* test(kb): add kb manager resilience tests

cover initialization failure and recovery scenarios to guard
against regressions in kb error handling

include reference assets under refs for test validation

---------

Co-authored-by: RC-CHN <1051989940@qq.com>

Author: piexian

astrbot/core/knowledge_base/kb_helper.py

@@ -108,6 +108,7 @@ async def _repair_and_translate_chunk_with_retry(
 class KBHelper:
     vec_db: BaseVecDB
     kb: KnowledgeBase
+    init_error: str | None
 
     def __init__(
         self,
@@ -122,6 +123,7 @@ def __init__(
         self.prov_mgr = provider_manager
         self.kb_root_dir = kb_root_dir
         self.chunker = chunker
+        self.init_error = None
 
         self.kb_dir = Path(self.kb_root_dir) / self.kb.kb_id
         self.kb_medias_dir = Path(self.kb_dir) / "medias" / self.kb.kb_id
@@ -148,21 +150,28 @@ async def get_ep(self) -> EmbeddingProvider:
     async def get_rp(self) -> RerankProvider | None:
         if not self.kb.rerank_provider_id:
             return None
-        rp: RerankProvider = await self.prov_mgr.get_provider_by_id(
+        rp: RerankProvider | None = await self.prov_mgr.get_provider_by_id(
             self.kb.rerank_provider_id,
         )  # type: ignore
         if not rp:
-            raise ValueError(
-                f"无法找到 ID 为 {self.kb.rerank_provider_id} 的 Rerank Provider",
+            logger.warning(
+                f"知识库 {self.kb.kb_name}({self.kb.kb_id}) 的 Rerank Provider({self.kb.rerank_provider_id}) 不可用，将跳过重排序。",
             )
+            return None
         return rp
 
     async def _ensure_vec_db(self) -> FaissVecDB:
         if not self.kb.embedding_provider_id:
             raise ValueError(f"知识库 {self.kb.kb_name} 未配置 Embedding Provider")
 
         ep = await self.get_ep()
-        rp = await self.get_rp()
+        rp: RerankProvider | None = None
+        try:
+            rp = await self.get_rp()
+        except Exception as e:
+            logger.warning(
+                f"知识库 {self.kb.kb_name}({self.kb.kb_id}) 初始化重排序能力失败，将跳过重排序: {e}",
+            )
 
         vec_db = FaissVecDB(
             doc_store_path=str(self.kb_dir / "doc.db"),
@@ -172,6 +181,8 @@ async def _ensure_vec_db(self) -> FaissVecDB:
         )
         await vec_db.initialize()
         self.vec_db = vec_db
+        # Clear stale init_error once initialization succeeds.
+        self.init_error = None
         return vec_db
 
     async def delete_vec_db(self) -> None:
@@ -183,7 +194,7 @@ async def delete_vec_db(self) -> None:
             shutil.rmtree(self.kb_dir)
 
     async def terminate(self) -> None:
-        if self.vec_db:
+        if hasattr(self, "vec_db") and self.vec_db:
             await self.vec_db.close()
 
     async def upload_document(

astrbot/core/knowledge_base/kb_mgr.py

@@ -1,4 +1,3 @@
-import traceback
 from pathlib import Path
 
 from astrbot.core import logger
@@ -56,8 +55,7 @@ async def initialize(self) -> None:
             logger.error(f"知识库模块导入失败: {e}")
             logger.warning("请确保已安装所需依赖: pypdf, aiofiles, Pillow, rank-bm25")
         except Exception as e:
-            logger.error(f"知识库模块初始化失败: {e}")
-            logger.error(traceback.format_exc())
+            logger.error(f"知识库模块初始化失败: {e}", exc_info=True)
 
     async def _init_kb_database(self) -> None:
         self.kb_db = KBSQLiteDatabase(DB_PATH.as_posix())
@@ -76,7 +74,14 @@ async def load_kbs(self) -> None:
                 kb_root_dir=FILES_PATH,
                 chunker=CHUNKER,
             )
-            await kb_helper.initialize()
+            try:
+                await kb_helper.initialize()
+            except Exception as e:
+                kb_helper.init_error = str(e)
+                logger.error(
+                    f"知识库 {record.kb_name}({record.kb_id}) 初始化失败: {e}",
+                    exc_info=True,
+                )
             self.kb_insts[record.kb_id] = kb_helper
 
     async def create_kb(
@@ -179,6 +184,20 @@ async def update_kb(
             return None
 
         kb = kb_helper.kb
+        previous_state = {
+            "kb_name": kb.kb_name,
+            "description": kb.description,
+            "emoji": kb.emoji,
+            "embedding_provider_id": kb.embedding_provider_id,
+            "rerank_provider_id": kb.rerank_provider_id,
+            "chunk_size": kb.chunk_size,
+            "chunk_overlap": kb.chunk_overlap,
+            "top_k_dense": kb.top_k_dense,
+            "top_k_sparse": kb.top_k_sparse,
+            "top_m_final": kb.top_m_final,
+        }
+        previous_init_error = kb_helper.init_error
+
         if kb_name is not None:
             kb.kb_name = kb_name
         if description is not None:
@@ -198,12 +217,47 @@ async def update_kb(
             kb.top_k_sparse = top_k_sparse
         if top_m_final is not None:
             kb.top_m_final = top_m_final
+
+        # Build a new helper first. Keep current vec_db alive until new init succeeds.
+        new_helper = KBHelper(
+            kb_db=self.kb_db,
+            kb=kb,
+            provider_manager=self.provider_manager,
+            kb_root_dir=FILES_PATH,
+            chunker=CHUNKER,
+        )
+
+        try:
+            await new_helper.initialize()
+        except Exception as e:
+            # Roll back in-memory settings and keep current helper available.
+            kb.kb_name = previous_state["kb_name"]
+            kb.description = previous_state["description"]
+            kb.emoji = previous_state["emoji"]
+            kb.embedding_provider_id = previous_state["embedding_provider_id"]
+            kb.rerank_provider_id = previous_state["rerank_provider_id"]
+            kb.chunk_size = previous_state["chunk_size"]
+            kb.chunk_overlap = previous_state["chunk_overlap"]
+            kb.top_k_dense = previous_state["top_k_dense"]
+            kb.top_k_sparse = previous_state["top_k_sparse"]
+            kb.top_m_final = previous_state["top_m_final"]
+            kb_helper.init_error = previous_init_error
+            logger.error(
+                f"知识库 {kb.kb_name}({kb.kb_id}) 重新初始化失败，继续使用旧实例: {e}",
+                exc_info=True,
+            )
+            return kb_helper
+
         async with self.kb_db.get_db() as session:
             session.add(kb)
             await session.commit()
             await session.refresh(kb)
 
-        return kb_helper
+        old_helper = kb_helper
+        self.kb_insts[kb_id] = new_helper
+        await old_helper.terminate()
+        new_helper.init_error = None
+        return new_helper
 
     async def retrieve(
         self,
@@ -215,11 +269,21 @@ async def retrieve(
         """从指定知识库中检索相关内容"""
         kb_ids = []
         kb_id_helper_map = {}
+        unavailable_kbs = []
         for kb_name in kb_names:
             if kb_helper := await self.get_kb_by_name(kb_name):
+                if kb_helper.init_error:
+                    unavailable_kbs.append((kb_name, kb_helper.init_error))
+                    logger.warning(f"知识库 {kb_name} 不可用: {kb_helper.init_error}")
+                    continue
                 kb_ids.append(kb_helper.kb.kb_id)
                 kb_id_helper_map[kb_helper.kb.kb_id] = kb_helper
 
+        # all requested KBs are unavailable
+        if not kb_ids and unavailable_kbs:
+            errors = "; ".join(f"{n}: {e}" for n, e in unavailable_kbs)
+            raise ValueError(f"所有请求的知识库均不可用: {errors}")
+
         if not kb_ids:
             return {}
 

astrbot/core/knowledge_base/retrieval/manager.py

@@ -184,12 +184,15 @@ async def retrieve(
                 first_rerank = vec_db.rerank_provider
                 break
         if first_rerank and retrieval_results:
-            retrieval_results = await self._rerank(
-                query=query,
-                results=retrieval_results,
-                top_k=top_m_final,
-                rerank_provider=first_rerank,
-            )
+            try:
+                retrieval_results = await self._rerank(
+                    query=query,
+                    results=retrieval_results,
+                    top_k=top_m_final,
+                    rerank_provider=first_rerank,
+                )
+            except Exception as e:
+                logger.warning(f"Rerank 执行失败，已跳过重排序并使用融合结果: {e}")
 
         return retrieval_results[:top_m_final]
 
@@ -229,10 +232,10 @@ async def _dense_retrieve(
 
                 all_results.extend(vec_results)
             except Exception as e:
-                from astrbot.core import logger
-
-                logger.warning(f"知识库 {kb_id} 稠密检索失败: {e}")
-                continue
+                logger.error(f"知识库 {kb_id} 稠密检索失败: {e}", exc_info=True)
+                if len(kb_ids) == 1:
+                    raise RuntimeError(f"知识库 {kb_id} 稠密检索失败: {e}") from e
+                # multi-KB: skip the faulty KB and continue
 
         # 按相似度排序并返回 top_k
         all_results.sort(key=lambda x: x.similarity, reverse=True)

astrbot/dashboard/routes/knowledge_base.py

@@ -314,7 +314,12 @@ async def list_kbs(self):
             # 转换为字典列表
             kb_list = []
             for kb in kbs:
-                kb_list.append(kb.model_dump())
+                kb_dict = kb.model_dump()
+                # include init_error from KBHelper if present
+                kb_helper = await kb_manager.get_kb(kb.kb_id)
+                if kb_helper and kb_helper.init_error:
+                    kb_dict["init_error"] = kb_helper.init_error
+                kb_list.append(kb_dict)
 
             return (
                 Response()

dashboard/src/i18n/locales/en-US/features/knowledge-base/index.json

@@ -10,7 +10,8 @@
     "loading": "Loading...",
     "documents": "Documents",
     "chunks": "Chunks",
-    "sessionConfig": "Session Config"
+    "sessionConfig": "Session Config",
+    "initError": "Initialization Failed"
   },
   "card": {
     "edit": "Edit",

dashboard/src/i18n/locales/ru-RU/features/knowledge-base/index.json

@@ -10,7 +10,8 @@
         "loading": "Загрузка...",
         "documents": "док.",
         "chunks": "фрагм.",
-        "sessionConfig": "Профиль"
+        "sessionConfig": "Профиль",
+        "initError": "Ошибка инициализации"
     },
     "card": {
         "edit": "Изменить",

dashboard/src/i18n/locales/zh-CN/features/knowledge-base/index.json

@@ -10,7 +10,8 @@
     "loading": "正在加载...",
     "documents": "文档",
     "chunks": "分块",
-    "sessionConfig": "会话配置"
+    "sessionConfig": "会话配置",
+    "initError": "初始化失败"
   },
   "card": {
     "edit": "编辑",

dashboard/src/views/knowledge-base/KBList.vue

@@ -27,14 +27,27 @@
     </div>
 
     <div v-else-if="kbList.length > 0" class="kb-grid">
-      <v-card v-for="kb in kbList" :key="kb.kb_id" class="kb-card" elevation="2" hover
-        @click="navigateToDetail(kb.kb_id)">
-        <div class="kb-card-content">
+      <v-card v-for="kb in kbList" :key="kb.kb_id" class="kb-card" elevation="2" :hover="!kb.init_error"
+        :class="{ 'kb-card-error': kb.init_error }"
+        @click="!kb.init_error && navigateToDetail(kb.kb_id)">
+        <!-- Error badge -->
+        <v-badge v-if="kb.init_error" color="error" icon="mdi-alert-circle"
+          class="kb-error-badge position-absolute" style="top: 0; right: 0; transform: translate(34%, -34%);" />
+        <div class="kb-card-content" :class="{ 'kb-card-content-error': kb.init_error }">
           <div class="kb-emoji">{{ kb.emoji || '📚' }}</div>
           <h3 class="kb-name">{{ kb.kb_name }}</h3>
-          <p class="kb-description text-medium-emphasis">{{ kb.description || '暂无描述' }}</p>
+          <p v-if="!kb.init_error" class="kb-description text-medium-emphasis">{{ kb.description || '暂无描述' }}</p>
 
-          <div class="kb-stats mt-4">
+          <!-- Error message display -->
+          <div v-if="kb.init_error" class="kb-error-panel mt-3 mb-2">
+            <div class="kb-error-title">
+              <v-icon size="16" color="error">mdi-close-circle</v-icon>
+              <span>{{ t('list.initError') }}</span>
+            </div>
+            <div class="kb-error-detail" :title="kb.init_error">{{ kb.init_error }}</div>
+          </div>
+
+          <div class="kb-stats mt-4" v-if="!kb.init_error">
             <div class="stat-item">
               <v-icon size="small" color="primary">mdi-file-document</v-icon>
               <span>{{ kb.doc_count || 0 }} {{ t('list.documents') }}</span>
@@ -45,8 +58,8 @@
             </div>
           </div>
 
-          <div class="kb-actions">
-            <v-btn icon="mdi-pencil" size="small" variant="text" color="info" @click.stop="editKB(kb)" />
+          <div class="kb-actions" :class="{ 'error-actions': kb.init_error }">
+            <v-btn v-if="!kb.init_error" icon="mdi-pencil" size="small" variant="text" color="info" @click.stop="editKB(kb)" />
             <v-btn icon="mdi-delete" size="small" variant="text" color="error" @click.stop="confirmDelete(kb)" />
           </div>
         </div>
@@ -478,6 +491,34 @@ onMounted(() => {
   box-shadow: 0 12px 24px rgba(0, 0, 0, 0.15) !important;
 }
 
+/* Error state card styles */
+.kb-card-error {
+  cursor: not-allowed;
+  border: 1px solid rgba(var(--v-theme-error), 0.3);
+  background-color: rgba(var(--v-theme-error), 0.02) !important;
+  overflow: visible; /* Allow badge to overflow */
+}
+
+.kb-card-error:hover {
+  transform: none;
+  box-shadow: 0 4px 12px rgba(var(--v-theme-error), 0.1) !important;
+  border-color: rgba(var(--v-theme-error), 0.5);
+}
+
+.kb-card-error .kb-emoji {
+  opacity: 0.7;
+  filter: grayscale(0.5);
+}
+
+.kb-card-error .kb-name {
+  color: rgba(var(--v-theme-on-surface), 0.7);
+}
+
+.kb-error-badge {
+  z-index: 10;
+  opacity: 0.9;
+}
+
 .kb-card-content {
   padding: 24px;
   display: flex;
@@ -488,6 +529,11 @@ onMounted(() => {
   position: relative;
 }
 
+.kb-card-content-error {
+  justify-content: center;
+  gap: 8px;
+}
+
 .kb-emoji {
   font-size: 56px;
   margin-bottom: 8px;
@@ -518,6 +564,36 @@ onMounted(() => {
   justify-content: center;
 }
 
+.kb-error-panel {
+  width: 100%;
+  text-align: left;
+  background: rgba(var(--v-theme-error), 0.08);
+  border: 1px solid rgba(var(--v-theme-error), 0.18);
+  border-radius: 10px;
+  padding: 10px 12px;
+}
+
+.kb-error-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: rgb(var(--v-theme-error));
+  margin-bottom: 4px;
+}
+
+.kb-error-detail {
+  font-size: 0.78rem;
+  line-height: 1.35;
+  color: rgba(var(--v-theme-on-surface), 0.82);
+  word-break: break-word;
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
 .stat-item {
   display: flex;
   align-items: center;