📄 AstrBot Pro 文件读取插件（File Reader Pro）

基于嵌入模型与向量检索的高效文件内容理解方案

本插件是 astrbot_plugin_file_reader 的增强版，代号 File Reader Pro。与传统“直接将文件全文塞入提示词”的做法不同，Pro 版采用现代 RAG（检索增强生成）架构，通过语义分块 + 向量嵌入 + 智能检索的方式，实现对文件内容的高效利用，显著降低上下文开销，提升问答准确率。

✨ 核心优势

🔍 更智能：基于语义的向量检索

• 不再粗暴拼接全文内容到 prompt。
• 使用嵌入模型（embedding_provider）将文本转化为高维向量。
• 通过 FAISS 实现快速近似最近邻搜索，仅返回最相关的片段。

⚡ 更高效：精准上下文注入

• 结合重排序模块（RerankProvider），进一步优化检索结果相关性。
• 显著减少 LLM 输入长度，节省 token，加快响应速度。
• 支持动态控制召回数量（retrieve_top_k），灵活平衡性能与精度。

🧩 更精细：语义感知的内容分块

• 采用 RecursiveCharacterChunker 进行递归分块，保留上下文连贯性。
• 可配置：
  • chunk_size：单块最大字符数（默认 512）
  • chunk_overlap：块间重叠长度（默认 100），防止语义断裂

📁 多文件支持 & 对话级隔离

• 支持在同一个对话中上传多个文件。
• 所有文件按 session_id 和 conversation_id 隔离存储与检索。
• 默认当前对话 conversation_id 中的文件会被检索（/new 了之后先前对话的文件不再被被检索了）。

🕒 智能生命周期管理

• 时间有效期：默认 60 分钟，超时自动清理（可配置）
• 使用轮次限制：默认最多参与 5 轮对话后清除（防冗余）
• 任一条件满足即触发清理，资源友好，无需手动干预。

🗑️ 用户可控：一键清理命令

支持以下指令清理当前会话中的所有文件数据：

/clear_file
/clean_file

清理操作作用于当前用户的 session_id，安全可靠。

📎 支持的文件格式

所有文件均调用专用解析器提取纯文本内容，确保结构化信息不失真。

⚙️ 配置选项（可通过 _conf_schema.json 自定义）

🛠️ 安装与使用

安装依赖

pip install -r requirements.txt

Linux 用户注意：若遇到文件类型识别问题，请安装 libmagic：

sudo apt-get install libmagic1

使用方法

1. 上传文件
   在 AstrBot 中直接发送文件即可，系统将自动完成：

   • 解析 → 分块 → 向量化 → 存储

2. 提问
   直接询问关于文件内容的问题，例如：

   “总结一下这个 PDF 的主要观点。”
   “这份代码里有没有调用外部 API？”

   插件会自动检索最相关内容并注入上下文。

3. 清理
   使用 /clear_file 或 /clean_file 清除当前会话的所有文件缓存。

🔬 技术原理简述

处理流程如下：

[文件] 
   ↓ 解析（read_xxx_to_text）
[纯文本]
   ↓ 递归分块（RecursiveCharacterChunker）
[文本块列表]
   ↓ 向量化（embedding_provider）
[向量表示]
   ↓ 存入 FAISS 向量库（FaissVecDB）
[可检索知识库]
   ↓ 查询时：相似度检索 + (可选) 重排序
[Top-K 相关段落]
   ↓ 注入 Prompt
[LLM 接收精炼上下文]

✅ 实现了从“全文硬塞”到“按需调用”的范式升级。

📝 注意事项

• 文件处理涉及计算资源消耗，请根据部署环境合理设置 chunk_size 和 max_file_size。
• 切换对话不会立即删除文件，仍可在有效期内返回继续使用。
• 过期文件将被后台自动回收，无需用户操心。

📦 版本历史

v2.0.0（当前）

• 引入向量化处理机制，告别全文注入
• 实现智能分块与 FAISS 向量存储
• 支持多文件共存与对话隔离
• 新增灵活配置项与标准清理命令
• 重构生命周期管理逻辑

v1.x.x

• 初始版本，基于 get_file() 实现基础文件读取
• 支持多种格式解析

💡 提示：如果你正在构建一个需要处理大量文档的 AI 助手，这个插件正是为“轻负担、高效率、强语义”而生。

如需进一步定制（如更换向量数据库、集成特定 embedding 模型），欢迎提交 Issue 或联系维护者。