第六周第二节那个RAG工业项目遇到的问题

完整改动清单

问题 1：数据库迁移失败 ------ `alembic_cfg` 变量未定义

现象：容器启动日志报 迁移过程出错: name 'alembic_cfg' is not defined。

根因： $start.sh$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/start.sh) 中 alembic_cfg = Config('alembic.ini') 原本只写在 if not table_exists: 分支内。非首次部署时该分支被跳过，后面无条件执行的 command.upgrade(alembic_cfg, 'head') 就引用了未定义的变量。

修复：

把 alembic_cfg = Config('alembic.ini') 移到 if 判断外面（ $第20行$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/start.sh#L20)），无论是否首次部署都会初始化。
调整执行顺序：先在 with engine.connect() 块内查表，块退出（连接关闭）后再执行 stamp/upgrade，避免连接占用。

重建容器后日志出现 数据库迁移完成!。

问题 2：PDF 解析失败 ------ XGBoost 旧模型格式被新版库移除（上传 0 切片的真正根源）

现象：上传 PDF 后解析阶段报错：

复制代码

Failed to load model: .../deepdoc/updown_concat_xgb.model
The binary format has been deprecated in 1.6 and removed in 3.1

文档解析出 0 个切片，后续无内容可入库。

根因：PDF 解析依赖的 deepdoc 模块使用 XGBoost 旧二进制格式的模型文件，而重新构建镜像时 pip 拉到了 XGBoost 3.1+，该版本彻底移除了旧格式读取支持。

修复：在 $requirements.txt:9$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/requirements.txt#L9) 锁定 xgboost==2.1.4（2.x 仍兼容旧二进制格式），重新构建镜像后模型正常加载、PDF 正常切片。

问题 3：前端"添加"按钮是死的（功能未实现）

现象：点"添加"无弹窗、无请求、无报错。

文件	改动
$contracts.tsx$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/frontend/src/pages/chat/component/contracts.tsx#L129)	按钮原本连 `onClick` 都没有。补全：点击 → 弹 Modal → 调 `api.repository.list()` 拉知识库文件 → Checkbox 多选 → 已添加项置灰防重复 → 确认走 `onAdd` 回调；搜索框补 `onChange` 本地过滤
$contracts.module.scss$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/frontend/src/pages/chat/component/contracts.module.scss)	新增弹窗文件列表样式
$chat/index.tsx$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/frontend/src/pages/chat/index.tsx#L359)	传 `onAdd` 回调，按 `document_name` 去重合并进 `documents` state

问题 4：上传"假成功" + ES 向量索引结构错误

现象：前端提示上传成功，但提问检索不到任何内容。

文件	改动
$es_conn.py$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/utils/es_conn.py#L137-L150)	原代码加载了 `mapping.json`（`q_1024_vec` 定义为 `dense_vector`）却从不使用，ES 自动建索引把向量当普通数组，kNN 失效。新增 `createIdx()`，`insert()` 前先用正确 mapping 建索引
$file_parse.py$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/file_parse.py#L137-L151)	解析/embedding/ES 插入失败原本只 `print` 不抛异常导致假成功，三处均改为 `raise Exception`
$chat_rt.py$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/router/chat_rt.py#L437)	新增 `POST /recreate_index` 重建接口；检索异常日志改为 `logger.exception()` 打完整堆栈（ $第182行$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/router/chat_rt.py#L182)）

配套操作：删除旧索引后重新上传文件。

问题 5：检索链路连环崩溃（命中了文档但引文为空）

现象：ES 有 25 条文档、向量检索命中，引文始终为空。

文件改动

$search_v2.py$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/search_v2.py#L375-L384) ① DashScope rerank API 返回 None（Key 无权限）会炸穿整个检索，加 try/except 自动降级 为本地混合排序；② 降级路径里 question_tks 入库时是 [] 而非字符串，.split() 崩溃（ $第298-305行$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/search_v2.py#L298-L305)），加 list/str 类型兼容

$query.py$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/query.py#L200-L211) hybrid_similarity 依赖 sklearn 但镜像和 requirements 里都没有，改用 numpy 手写 cosine，零新增依赖

文件	改动
$search_v2.py$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/search_v2.py#L375-L384)	① DashScope rerank API 返回 None（Key 无权限）会炸穿整个检索，加 try/except 自动降级为本地混合排序；② 降级路径里 `question_tks` 入库时是 `[]` 而非字符串，`.split()` 崩溃（ $第298-305行$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/search_v2.py#L298-L305)），加 list/str 类型兼容
$query.py$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/query.py#L200-L211)	`hybrid_similarity` 依赖 sklearn 但镜像和 requirements 里都没有，改用 numpy 手写 cosine，零新增依赖

问题 6：Docker 挂载路径错误（所有后端修改不生效的总开关）

现象：代码反复确认改对、容器里也能查到新代码，但运行行为和报错完全不变。

根因： $docker-compose.yml$ (file:///d:/保研资料/wangzhe/第六周：RAG%20(Part%202)：RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/docker-compose.yml#L24) 的挂载 ./app:/app/app 把宿主机代码挂到了容器 /app/app/ 嵌套子目录，而 Dockerfile 是 WORKDIR /app + COPY . /app，服务实际运行镜像里 /app/ 下的旧代码，新代码从未被加载。

修复：

yaml 复制代码

- ./app:/app    # 原 ./app:/app/app

挂载变更需 docker compose up -d --force-recreate swxy_api 重建容器（普通 restart 不重读挂载）。

故障链总览