安全地将字符串环境变量转换为整数，非法值时回退到 fallback。

获取 OCR 引擎实例，自动选择最优后端。 尝试顺序: 1. rapidocr_paddle: 支持 det_use_cuda、cls_use_cuda、rec_use_cuda 参数 2. rapidocr_onnxruntime: 无 GPU

执行完整的混合检索 + 重排序流程。 这是本系统的核心检索方法，包含以下步骤: ┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ 用户查询

检查 QA 系统是否已初始化；未初始化则抛出 503。

关闭数据库连接，释放资源。 应在程序退出前或不再需要数据库操作时调用，避免连接泄漏。 推荐使用 try...finally 或在上下文管理器中调用。

创建 PyTorch Dataset 对象，用于 Trainer 的训练和评估。 参数: encodings: Tokenizer 的输出（BatchEncoding） labels (list[int]): 整数标

获取指定会话的对话历史（公开接口）。 参数: session_id (str): 会话唯一标识。 返回: list[dict]: 对话历史列表，每个元素含 question 和 answer 字段。

执行 BM25 关键词检索。 检索流程: 1. 验证输入有效性 2. 检查 BM25 索引是否就绪 3. 查询 Redis 缓存 4. 对查询文本分词

为给定的用户查询选择最优检索策略。 处理流程: 1. 将查询填入策略选择 Prompt 模板 2. 调用 LLM 获取策略建议 3. 安全处理返回值（strip 空白，None 降级为默认策略

将数据以 JSON 格式存入 Redis。 自动对 value 进行 json.dumps 序列化，支持字典、列表等复杂类型。 参数: key (str): 缓存键名。 value (any): 要

从数据库获取指定会话的最近 N 轮对话历史。 查询策略: 1. 按时间戳倒序排列，取最近的 LIMIT 条记录 2. 将数据库行转换为 {"question": ..., "answer": ...} 字典列表

执行完整的 RAG 流程，生成最终答案。 完整流程: ┌─────────────────────────────────────────────────┐ │ 1. BERT 查询分类 → 通用知识 / 专业咨询

从 Redis 获取 JSON 格式存储的数据并反序列化。 参数: key (str): 缓存键名。 返回: any | None: 反序列化后的 Python 对象；若键不存在或读取失败返回 No

加载 BERT 分类模型。 加载优先级: 1. 如果 model_path 下存在微调后的模型（含 model.safetensors）→ 直接加载 2. 否则 → 从 HuggingFace 下载 bert-bas

对单个查询进行意图分类。 推理流程: 1. 检查模型是否已加载 2. 切换到 eval 模式（关闭 Dropout） 3. 分词 + 移动到设备 4. 前向传播（无梯度

对文本数据和标签进行预处理（分词 + 标签编码）。 处理步骤: 1. 使用 BERT Tokenizer 进行分词、截断、填充 2. 将文本标签映射为整数 (通用知识→0, 专业咨询→1) 参数:

对输入文本进行预处理：转小写 → jieba 分词。 处理步骤: 1. text.lower(): 将英文字母统一转为小写，避免大小写差异影响匹配 2. jieba.lcut(): 使用 jieba 的精确模式分词，返回词语列表 参数:

加载文档并进行父子块分层切分。 这是文档进入向量数据库前的完整预处理管道: ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ │ 加载文档 │───→│ 父块切分 (1200)

执行完整的查询流程，依次尝试关键词匹配和语义检索。 这是系统的核心查询方法，采用两级检索策略: ┌─────────────────────────────────────────────────────────┐ │ 用户查询

使用 BERT 语义模型对文本进行分割。 处理流程: 1. 若为 PDF 文本: 清理多余换行、压缩空白 2. 使用已加载的达摩院 BERT 文档分割模型 3. 运行模型推理，获取语义边界

使用标注数据训练 BERT 分类模型。 训练流程: 1. 加载 JSONL 格式的训练数据 2. 按 80/20 比例划分训练集和验证集 3. 数据预处理（分词 + 标签编码）

更新指定会话的对话历史。 操作流程: 1. 插入当前轮的问答对到 conversations 表 2. 删除超出保留数量的旧记录（仅保留最近 5 轮） 3. 使用子查询技巧解决 MySQL 不

使用环境变量覆盖配置值。 环境变量优先级高于 config.ini 中的值， 主要用于注入敏感信息（密码、API Key），避免在配置文件中明文存储。

创建或加载 Milvus 集合。 逻辑: - 集合不存在 → 定义 Schema + 创建索引 + 创建集合 - 集合已存在 → 直接加载到内存 索引类型: - 稠密向量:

将 Milvus 搜索结果中的一条命中记录转换为 LangChain Document 对象。 参数: hit (dict): Milvus 的一条搜索结果，包含 text 和元数据字段。 返回:

构建策略选择的 Few-Shot Prompt 模板。 Few-Shot 设计原则: 1. 每种策略包含清晰的描述和适用场景说明 2. 每类策略提供 1-2 个具体示例 3. 示例覆盖不同学科

从子块列表中提取去重的父文档。 原理: 父子块策略中，一个父块可能被切分成多个子块。 在检索阶段，多个子块可能命中同一个父块。 此方法将子块映射回父文档并去重，确保返回的上下文不重复。

加载问答数据并构建 BM25 索引。 数据加载优先级: 1. 优先从 Redis 缓存读取（快速启动） 2. 若缓存未命中，从 MySQL 加载 → 分词 → 存入 Redis 缓存 缓存键:

回溯问题检索策略。 原理: 用户的问题可能包含过多细节或特定约束，导致检索范围过窄。 通过将复杂问题"回溯"为更基础的版本，扩大检索范围。 例如: "我有100亿条数据想存到Milvus可以吗

HyDE (Hypothetical Document Embeddings) 策略。 原理: 用户查询通常很短（例如"AI的应用"），而知识库文档很长。 短查询和长文档在语义空间中距离较远，直接检索效果差。

子查询检索策略。 原理: 复杂查询包含多个子问题，每个子问题可能匹配不同的文档。 例如"比较 Java 和 Python" → 拆为"Java 的特点"和"Python 的特点"， 分别检索两

对 BM25 原始分数应用 Softmax 归一化。 Softmax 公式: softmax(x_i) = exp(x_i - max(x)) / Σ exp(x_j - max(x)) 减去最大值 (max(x)) 是为

使用正则表达式从文本末尾开始分割，支持保留分隔符。 与 str.split 的区别: - 支持正则表达式分隔符 - 从末尾开始分割（更适合中文阅读习惯） - 可选保留分隔符在结果中（keep_separator=True）

将文档块批量插入（或更新）到 Milvus 集合。 使用 Upsert 语义: - id 不存在 → 插入新记录 - id 已存在 → 更新已有记录（适合增量更新场景） 处理流程:

回溯问题简化模板。 策略原理: 用户的问题可能包含过多细节或特定约束条件，导致检索范围过窄。 通过将复杂问题"回溯"为更基础、更通用的版本，扩大检索范围， 然后再结合原始需求筛选结果。

调用 DashScope LLM API，获取策略选择结果。 使用低温度 (temperature=0.1) 以获得更确定性的输出， 提高策略选择的一致性和可靠性。 参数: prompt (str): 填充

清空指定会话的全部历史记录。 参数: session_id (str): 要清空的会话 ID。 返回: bool: 清空成功返回 True，失败返回 False。 使用场景:

创建 jpkb（精品课标）数据表。 表结构: - id (INT, 自增主键): 记录的唯一标识 - subject_name (VARCHAR(20)): 学科名称 - question (

从 .docx 文件提取全部文本内容。 处理流程: 1. 打开文档 2. 按 XML 元素顺序迭代段落和表格 3. 段落: 提取直接文本 + 嵌入图片 OCR 4. 表

在给定测试集上评估模型，输出分类报告和混淆矩阵。 参数: texts (list[str]): 测试文本列表 labels (list[int]): 真实标签列表（整数） eval_outpu

根据问题文本查询对应的答案。 用于 BM25 匹配成功后获取精确答案。 参数: question (str): 问题文本，需与数据库中存储的完全一致。 返回: str | None

获取 jpkb 表中的所有问题。 此方法用于 BM25 索引的初始化阶段，一次性加载所有问题文本。 返回: list[tuple]: 问题列表，每个元素是单元素元组 (问题文本,)。

根据查询文本获取缓存的答案。 此方法专用于答案缓存场景。与 set_data 配合使用： - 存储: self.set_data(f'answer:{query}', answer) - 读取: self.get_a

HyDE (Hypothetical Document Embeddings) 假设答案生成模板。 HyDE 策略的核心思想: 用户查询往往过于简短，与知识库中详细文档的语义空间不匹配。 通过让 LLM 先生成一个"

对图片执行 OCR，返回识别的文字。 处理流程: 1. 获取 OCR 引擎实例 2. 直接传入图片路径给 OCR 引擎 3. 提取识别结果中的文字行 4. 以换行符连接

初始化 MySQL 中的会话历史表 (conversations)。 表结构: - id: 自增主键 (INT AUTO_INCREMENT) - session_id: 会话唯一标识 (VARCHAR(36)，用于

从 CSV 文件批量导入数据到 jpkb 表。 CSV 文件格式要求: 必需列: 学科名称, 问题, 答案 编码: 需与 pandas read_csv 默认兼容（通常为 UTF-8） 处理流程:

从指定目录递归加载所有支持的文档文件，并添加元数据。 处理流程: 1. 遍历目录及所有子目录 2. 根据文件扩展名选择对应的加载器 3. 加载文档内容（PDF/DOCX/PPT 包含图片 OCR） 4. 为每个文档添

主函数 - 提供命令行交互式问答界面。 功能: 1. 初始化 IntegratedQASystem（完成所有子系统的连接） 2. 生成唯一的会话 ID（UUID4） 3. 进入 REPL 循环：读取用户输入 → 执行查询 → 输出答

RAG 子系统主函数，支持数据处理和交互式查询两种模式。 参数: query_mode (bool): True 为查询模式，False 为数据处理模式。 directory_path (str): 数据目录路径。查询模式下不使用。 数据

主函数 - 提供 MySQL 问答子系统的独立命令行界面。 交互流程: 1. 初始化 MySQLQASystem 2. 进入 REPL 循环 3. 用户输入查询 → 系统返回 BM25 匹配结果 4. 输入 'exi

从 PDF 提取全部文本内容，包括原生文字和图片 OCR 结果。 处理流程（逐页）: 1. 获取页面原生文本层文字 2. 获取页面中的所有图片元信息 3. 筛选大尺寸图片（过滤小图标/Logo

从 PPT 文件提取全部文本内容。 处理内容类型: - 文本框 (Text Frame): 直接读取 shape.text - 表格 (Table): 遍历行→单元格→段落 - 图片 (Pic

执行关键词匹配查询（不包含 RAG 语义检索）。 查询流程: 1. 记录开始时间 2. 调用 bm25_search.search 进行关键词匹配 3. 若匹配成功，返回答案；否则返回兜底提示

RAG 答案生成提示词模板。 指导原则: - 优先基于检索到的上下文回答问题 - 若无上下文则基于 LLM 自身知识回答 - 无法回答时提供客服电话作为降级方案 - 若

根据指定策略执行检索，返回最终候选文档。 此方法是策略到检索的统一入口，根据策略名称分派到对应的检索方法。 分派逻辑: - "回溯问题检索" → _retrieve_with_backtracking

旋转图片以校正 PDF 中的旋转页面。 旋转原理: - 使用 OpenCV 的仿射变换 (Affine Transform) - 绕图片中心旋转指定角度 - 自动扩展画布以容纳旋转后的完整图片

保存微调后的模型和分词器到 model_path。 同时保存: - 模型权重 (model.safetensors) - 模型配置 (config.json) - 分词器配置 (tokeniz

初始化日志系统，配置日志器 (Logger)、处理器 (Handler) 和格式化器 (Formatter)。 设计要点: 1. 自动创建日志文件所在的目录（如果不存在） 2. 使用 logger.handlers 检查避免重复添加处理器（防止多次

子查询分解模板。 策略原理: 复杂查询可能包含多个子问题，一次性检索效果不佳。 将复杂查询拆分为多个简单子查询，每个子查询独立检索， 最后合并去重，可以覆盖问题的多个方面。

验证关键配置项是否已正确设置，在系统启动时尽早发现配置问题。 检查项: - LLM API Key 是否已配置 - LLM Base URL 是否已配置 - 块大小参数是否合理（child <

初始化集成问答系统，依次建立所有子系统的连接。 初始化顺序: 1. 加载配置和日志 2. 连接 MySQL 数据库 3. 连接 Redis 缓存 4. 初始化 BM25

初始化配置管理器，加载并解析配置文件。 参数: config_file (str): 配置文件相对于本模块文件的路径，默认为 '../config.ini'。 路径会被解析为绝对路

初始化 Word 加载器。 参数: filepath (str): .docx 文件的路径。

初始化图片 OCR 加载器。 参数: img_path (str): 图片文件的路径。

初始化 PPT 加载器。 参数: filepath (str): PPT/PPTX 文件的绝对或相对路径。

初始化 PDF 加载器。 参数: file_path (str): PDF 文件的绝对或相对路径。

初始化 RAG 系统。 参数: vector_store (VectorStore): 已初始化的向量存储实例。 llm (callable): LLM 调用函数，签名应为 fn(prompt: str) -> st

初始化策略选择器，建立 LLM 连接并加载 Prompt 模板。

初始化查询分类器。 处理流程: 1. 确定模型路径（默认: rag_qa/core/bert_query_classifier/） 2. 加载 BERT 分词器（从本地 bert-base-chinese 模型）

初始化向量存储，依次完成: 加载模型 → 建集合 → 连接 Milvus 参数: collection_name (str): Milvus 集合名称，相当于关系数据库中的"表" host (str):

初始化语义分割器。 参数: pdf (bool): 文本来源是否为 PDF。PDF 文本需要额外的格式清理。 默认 False。 **kwargs: 传递给父类 Cha

初始化中文递归文本分割器。 参数: separators (list[str], optional): 自定义分隔符优先级列表。 默认按中文标点优先

初始化 MySQL 问答系统的各个组件。

建立与 Redis 服务器的连接。 使用 Config 中的参数：主机、端口、密码、数据库编号。 启用 decode_responses=True，使 get/set 操作自动进行 bytes ↔ str 转换，简化代码。

初始化 BM25 检索器，加载数据并构建索引。 参数: redis_client (RedisClient): 已初始化的 Redis 客户端。 mysql_client (MySQLClient): 已初始化的 M

建立与 MySQL 数据库的连接。 使用 Config 中读取的数据库参数（主机、用户名、密码、数据库名）。 连接成功后会创建一个游标对象，用于后续的 SQL 执行。 异常: pymysql.MySQLEr

递归分割文本的核心方法（重写父类方法）。 递归逻辑: 1. 在当前分隔符列表中，找到第一个能在 text 中匹配到的分隔符 2. 用该分隔符切分文本 3. 对切分后小于 chunk_size

LLM 调用函数（非流式）。 参数: prompt (str): 完整的提示词文本。 返回: str: LLM 生成的答复；若客户端不可用或调用失败，返回错误提示。

调用 DashScope LLM API 生成答案（非流式版本）。 此方法供 RAGSystem 的内部检索策略使用，因为策略选择、查询分解等 操作需要返回完整字符串结果。 参数: prompt (str)

调用 DashScope LLM API 生成答案（流式版本）。 此方法使用 Server-Sent Events (SSE) 流式传输，逐 token 产出内容， 适合需要实时展示生成过程的场景，可显著降低用户感知延迟。 参数:

SSE 流式问答接口。 接收用户查询，调用 IntegratedQASystem.query() 获取答案， 通过 Server-Sent Events 流式返回，前端可逐字渲染。 请求体 (JSON): - query (str): 用户查询文

清空指定会话的全部对话历史。

计算评估指标（准确率）。 参数: eval_pred: Trainer 传入的 EvalPrediction 对象，包含 logits 和 labels。 返回: dict: 指标字典，如 {"ac

递归提取形状中的文本（内部函数）。 使用 nonlocal 声明访问和修改外部函数中的 resp 变量， 避免每次递归都传递 resp。 参数: shape: pyt

列出所有会话及其最近一次提问（供侧边栏历史列表用）。 按最近活动时间倒序排列，最多返回 100 条。

获取指定会话的最近 5 轮对话历史。

返回系统中所有可用的学科类别列表。

按文档 XML 元素顺序迭代段落和表格。 这是 python-docx 官方推荐的内容按序迭代方案。 直接使用 doc.paragraphs + doc.tables 无法保证顺序， 因为 Word

延迟加载模式：提取文本后返回单个 Document。 Returns: Iterator[Document]

延迟加载模式：对图片执行 OCR 后返回单个 Document。 Returns: Iterator[Document]

延迟加载模式：提取文本后返回单个 Document。 Returns: Iterator[Document]

延迟加载模式：逐文档产出，适合大文件场景。 Returns: Iterator[Document]: 一次产出单个 Document 的生成器。

应用启动时初始化 QA 系统；若后端服务不可用则打印告警但不阻塞启动。