docs: sync failure semantics and rollback behavior

Author: MisonL

CHANGELOG.md

@@ -13,6 +13,9 @@
 ### 稳定性与检索
 
 - 修复聊天会话和召回测试中的异步输入问题，消除 `asyncio.run()` 与事件循环冲突。
+- 收紧 Provider 失败契约：当凭证、SDK 或远端调用失败时，统一改为显式报错并保留日志，不再返回占位回答、空 embedding 或零分 rerank 结果。
+- 修复聊天 `/config` 切换 LLM 时的状态回滚问题；当新模型加载失败时，活动模型配置会回退到旧值，避免界面状态与实际模型实例不一致。
+- 修正 `grok` 与 `volcengine` Provider 的真实导入链路，并新增 Provider 导入烟测，避免“测试通过但模块无法导入”的假收敛。
 - 优化知识库重建流程，向量化时不再加载旧索引追加写入。
 - 增强本地检索质量：索引文本引入来源文件标题上下文，聊天检索使用意图文本而不是原始提示约束语。
 - 完成父子分段检索、RRF 融合、sidecar 父文档存储等 RAG 核心能力的适配与校验。

README.md

@@ -19,7 +19,7 @@
 
 - **全链路异步流水线**: 从文档 ETL 到混合检索及 LLM 生成的全过程异步化。
 - **高维索引平衡**: 哈希/向量检索与传统关键词检索的混合策略及加权融合。
-- **Provider 解耦架构**: 针对主流模型供应商（Google, OpenAI, Anthropic 等）的标准化抽象与容错处理。
+- **Provider 解耦架构**: 针对主流模型供应商（Google, OpenAI, Anthropic 等）的标准化抽象、异常隔离与显式失败处理。
 - **工程化最佳实践**: 采用 `uv` 环境管理、CSE 性能传感器及 `tenacity` 指数退避重试机制。
 
 ---
@@ -34,6 +34,10 @@
 - **⚙️ 交互式配置控制**: 通过 `/config` 命令在运行时动态调整全局参数，包括检索 Top-K、权重配比及重试策略。
 - **🧪 架构级验证工具**: 内置 `AGENTS.md` 指导原则与全面的 `pytest` 测试套件，确保每一行核心逻辑的可重复性验证。
 
+说明：
+1. 当模型提供商凭证、SDK 初始化或远端调用失败时，系统会显式报错并保留日志，不再返回占位回答、空 embedding 或零分 rerank 结果。
+2. 聊天界面通过 `/config` 切换 LLM 时，如果新模型加载失败，会自动回退到当前活动模型配置，避免界面状态与实际模型实例不一致。
+
 ---
 
 ## 📂 目录结构

docs/user_guide/llm-providers.md

@@ -2,6 +2,12 @@
 
 PyRAG-Kit 的一个核心优势是其高度的灵活性和可扩展性，尤其体现在对多种大语言模型 (LLM) 提供商的无缝支持上。您可以根据自己的需求和资源，轻松切换和配置不同的模型。
 
+## 失败语义说明
+
+- 当 Provider 的凭证缺失、SDK 导入失败或远端 API 调用失败时，系统会显式报错并记录日志。
+- 聊天模型失败时，不再返回占位回答；Embedding 或 Rerank 失败时，也不再返回空向量或零分结果伪装为成功。
+- 在聊天界面通过 `/config` 切换 LLM 时，如果新模型加载失败，系统会自动保留当前活动模型配置。
+
 ## 支持的模型提供商
 
 本项目通过模块化的提供商 (Provider) 设计，内置了对以下主流和本地模型服务的支持：