Archive Agent

开发 Python

🚀 ⚡ Archive Agent

Archive Agent 是一款智能文件索引器，具备 AI 搜索（RAG 引擎）、自动 OCR 以及 MCP 接口等功能。它能让你使用自然语言查找文件并提问，支持对多种文件类型进行索引和处理。

https://github.com/user-attachments/assets/1cd8211e-6e5b-4e61-8ccc-74c140697abc

🚀 快速开始

请先安装以下依赖：

🐳 Docker（用于运行 Qdrant 服务器）
🐍 Python >= 3.10（核心运行时，通常已安装）

Ubuntu / Linux Mint

在你选择的当前目录中安装 Archive Agent，运行以下命令：

git clone https://github.com/shredEngineer/Archive-Agent
cd Archive-Agent
chmod +x install.sh
./install.sh

install.sh 脚本将按顺序执行以下步骤：

下载并安装 uv（用于 Python 环境管理）
安装自定义 Python 环境
安装 spaCy 分词器模型（用于分块）
安装 pandoc（用于文档解析）
下载并安装带有持久存储和自动重启功能的 Qdrant Docker 镜像
为当前用户安装全局 archive-agent 命令

🚀 Archive Agent 已安装完成！

👉 请接下来完成 AI 提供商设置。
（之后，你就可以运行 Archive Agent 了！）

✨ 主要特性

多文件类型索引：支持对纯文本、文档、PDF、图像等多种文件类型进行索引。
自动 OCR 与实体提取：利用自动 OCR 和实体提取技术处理图像。
AI 搜索与查询：可使用 AI（如 OpenAI、Ollama、LM Studio）搜索和查询文件。
MCP 服务器集成：包含用于通过 IDE 或 AI 扩展实现自动化的 MCP 服务器。

📦 安装指南

安装要求

请在继续之前安装以下依赖：

🐳 Docker（用于运行 Qdrant 服务器）
🐍 Python >= 3.10（核心运行时，通常已安装）

Ubuntu / Linux Mint

此安装方法适用于任何基于 Ubuntu 的 Linux 发行版（如 Linux Mint）。在你选择的当前目录中安装 Archive Agent，运行以下命令：

git clone https://github.com/shredEngineer/Archive-Agent
cd Archive-Agent
chmod +x install.sh
./install.sh

install.sh 脚本将按顺序执行以下步骤：

下载并安装 uv（用于 Python 环境管理）
安装自定义 Python 环境
安装 spaCy 分词器模型（用于分块）
安装 pandoc（用于文档解析）
下载并安装带有持久存储和自动重启功能的 Qdrant Docker 镜像
为当前用户安装全局 archive-agent 命令

🚀 Archive Agent 已安装完成！

👉 请接下来完成 AI 提供商设置。
（之后，你就可以运行 Archive Agent 了！）

💻 使用示例

基础用法

跟踪文件

archive-agent include "~/Documents/**" "~/Images/**"
archive-agent update

启动 GUI

archive-agent

从命令行提问

archive-agent query "Which files mention donuts?"

高级用法

查看命令列表

archive-agent

创建或切换配置文件

archive-agent switch "My Other Profile"

打开当前配置文件的配置

archive-agent config

添加包含模式

archive-agent include "~/Documents/*.txt"

添加排除模式

archive-agent exclude "~/Documents/*.txt"

删除包含/排除模式

archive-agent remove "~/Documents/*.txt"

列出包含/排除模式

archive-agent patterns

解析模式并跟踪文件

archive-agent track

列出跟踪的文件

archive-agent list

列出更改的文件

archive-agent diff

将更改的文件提交到数据库

archive-agent commit

组合跟踪和提交

archive-agent update

搜索文件

archive-agent search "Which files mention donuts?"

查询文件

archive-agent query "Which files mention donuts?"

启动 Archive Agent GUI

archive-agent gui

启动 MCP 服务器

archive-agent mcp

📚 详细文档

AI 提供商设置

Archive Agent 允许你在不同的 AI 提供商之间进行选择：

远程 API（性能较高但成本较高，隐私性较差）：
- OpenAI：需要 OpenAI API 密钥。
本地 API（性能较低但成本较低，隐私性最佳）：
- Ollama：需要本地运行 Ollama。
- LM Studio：需要本地运行 LM Studio。

💡 提示：启动时会提示你选择 AI 提供商；请参阅：运行 Archive Agent。

📌 注意：你可以在 Archive Agent 设置中自定义 AI 提供商使用的特定模型。但是，你不能更改现有配置文件的 AI 提供商，因为嵌入将不兼容；若要选择不同的 AI 提供商，请创建一个新的配置文件。

OpenAI 提供商设置

如果选择 OpenAI 提供商，Archive Agent 需要 OpenAI API 密钥。导出你的 OpenAI API 密钥，将 sk-... 替换为你的实际密钥并运行以下命令：

echo "export OPENAI_API_KEY='sk-...'" >> ~/.bashrc && source ~/.bashrc

这将为当前用户持久化导出。

💡 提示：OpenAI 不会使用你的数据进行训练。

Ollama 提供商设置

如果选择 Ollama 提供商，Archive Agent 需要 Ollama 在 http://localhost:11434 上运行。

如何安装 Ollama

使用默认的 Archive Agent 设置，预计需要安装以下 Ollama 模型：

ollama pull llama3.1:8b             # for chunk/rerank/query
ollama pull llava:7b-v1.6           # for vision
ollama pull nomic-embed-text:v1.5   # for embed

💡 提示：Ollama 在没有 GPU 的情况下也能工作。建议至少有 32 GiB 内存以确保性能流畅。

LM Studio 提供商设置

如果选择 LM Studio 提供商，Archive Agent 需要 LM Studio 在 http://localhost:1234 上运行。

如何安装 LM Studio

使用默认的 Archive Agent 设置，预计需要安装以下 LM Studio 模型：

meta-llama-3.1-8b-instruct              # for chunk/rerank/query
llava-v1.5-7b                           # for vision
text-embedding-nomic-embed-text-v1.5    # for embed

💡 提示：LM Studio 在没有 GPU 的情况下也能工作。建议至少有 32 GiB 内存以确保性能流畅。

支持的操作系统

Archive Agent 已在以下配置中进行了测试：

Ubuntu 24.04（PC x64）

如果你已成功在不同的设置中安装并测试了 Archive Agent，请告知我，我会将其添加到此列表中！

如何选择要跟踪的文件

Archive Agent 使用模式来选择文件：

模式可以是实际的文件路径。
模式可以是包含通配符的路径，解析为实际的文件路径。

💡 模式必须指定为（或解析为）绝对路径，例如 /home/user/Documents/*.txt（或 ~/Documents/*.txt）。 💡 使用通配符 * 匹配给定目录中的任何文件。 💡 使用通配符 ** 匹配任何文件以及零个或多个目录、子目录和目录的符号链接。

有 包含模式 和 排除模式：

解析后的排除文件集将从解析后的包含文件集中移除。
Archive Agent 仅跟踪剩余的文件集（包含但不排除）。
隐藏文件始终被忽略！

这种方法让你对要跟踪的特定文件或文件类型有最佳的控制。

MCP 工具

Archive Agent 通过 MCP 公开了以下工具：

MCP 工具	等效的 CLI 命令(s)	参数(s)	描述
`get_patterns`	`patterns`	无	获取包含/排除模式的列表。
`get_files_tracked`	`track` 然后 `list`	无	获取跟踪的文件列表。
`get_files_changed`	`track` 然后 `diff`	无	获取更改的文件列表。
`get_search_result`	`search`	`question`	获取与问题相关的文件列表。
`get_answer_rag`	`query`	`question`	使用 RAG 获取问题的答案。

📌 注意：这些命令是只读的，防止 AI 更改你的 Qdrant 数据库。

💡 提示：只需在你的 IDE 或 AI 扩展中输入 #get_answer_rag（例如）即可直接调用该工具。

更新 Archive Agent

如果你刚刚安装了 Archive Agent，则无需立即执行此步骤。但是，为了获得最新功能，你应该定期更新你的安装。

在安装目录中运行以下命令来更新你的 Archive Agent 安装：

./update.sh

📌 注意：如果更新不起作用，请尝试删除安装目录，然后再次安装 Archive Agent。你的配置和数据安全地存储在其他位置；有关详细信息，请参阅 Archive Agent 设置和 Qdrant 数据库。

💡 提示：若要同时更新 Qdrant Docker 镜像，请运行以下命令：

sudo ./manage-qdrant.sh update

Archive Agent 设置

Archive Agent 设置以配置文件文件夹的形式组织在 ~/.archive-agent-settings/ 中。例如，default 配置文件位于 ~/.archive-agent-settings/default/。当前使用的配置文件存储在 ~/.archive-agent-settings/profile.json 中。

📌 注意：要删除配置文件，只需删除配置文件文件夹。这不会删除 Qdrant 集合（请参阅 Qdrant 数据库）。

配置文件配置

配置文件配置包含在配置文件文件夹中的 config.json 中。

💡 提示：使用 config CLI 命令在 nano 编辑器中打开当前配置文件的配置（JSON）（请参阅在 nano 中打开当前配置文件的配置）。 💡 提示：使用 switch CLI 命令切换到新的或现有的配置文件（请参阅创建或切换配置文件）。

键	描述
`config_version`	配置版本
`mcp_server_port`	MCP 服务器端口（默认 `8008`）
`ocr_strategy`	中的 OCR 策略
`ocr_auto_threshold`	`auto` OCR 策略解析为 `relaxed` 而不是 `strict` 的最小字符数
`chunk_lines_block`	分块时每个块的行数
`qdrant_server_url`	Qdrant 服务器的 URL
`qdrant_collection`	Qdrant 集合的名称
`retrieve_score_min`	检索的块的最小相似度分数（`0`...`1`）
`retrieve_chunks_max`	检索的最大块数
`rerank_chunks_max`	重新排序后保留的前几个块数
`expand_chunks_radius`	为每个重新排序的块前置和追加的前后块数
`ai_provider`	中的 AI 提供商
`ai_server_url`	AI 服务器的 URL
`ai_model_chunk`	用于分块的 AI 模型
`ai_model_embed`	用于嵌入的 AI 模型
`ai_model_rerank`	用于重新排序的 AI 模型
`ai_model_query`	用于查询的 AI 模型
`ai_model_vision`	用于视觉的 AI 模型（`""` 禁用视觉）
`ai_vector_size`	嵌入的向量大小（用于 Qdrant 集合）
`ai_temperature_query`	查询模型的温度

监视列表

配置文件监视列表包含在配置文件文件夹中的 watchlist.json 中。

监视列表仅由以下命令管理：

include / exclude / remove
track / commit / update

AI 缓存

每个配置文件文件夹还包含一个 ai_cache 文件夹。

AI 缓存确保在给定的配置文件中：

同一图像仅进行一次 OCR。
同一文本仅进行一次分块。
同一文本仅进行一次嵌入。
同一块组合仅进行一次重新排序。

这样，如果提交被中断，Archive Agent 可以快速从上次中断的地方继续。

要在单次提交中绕过 AI 缓存，请在 commit 或 update 命令中传递 --nocache 选项（请参阅将更改的文件提交到数据库和组合跟踪和提交）。

💡 提示：查询从不缓存，因此你始终可以获得最新的答案。

📌 注意：要清除整个 AI 缓存，只需删除配置文件的缓存文件夹。

📌 技术说明：Archive Agent 使用由文本/图像字节以及用于分块、嵌入、重新排序和视觉的 AI 模型名称组成的复合哈希来键控缓存。缓存键是确定性的，并且每当你更改分块、嵌入或视觉 AI 模型名称时都会生成更改。由于缓存条目会永久保留，切换回先前的 AI 模型名称组合将再次访问“旧”键。

Qdrant 数据库

Qdrant 数据库存储在 ~/.archive-agent-qdrant-storage/ 中。

📌 注意：此文件夹由以 root 身份运行的 Qdrant Docker 镜像创建。

💡 提示：访问你的 Qdrant 仪表板以管理集合和快照。

开发者指南

Archive Agent 是为教育目的从头编写的（软件的两端）。

💡 提示：跟踪 test_data/ 可以让你从一些测试数据开始。

重要模块

要开始开发，请查看以下重要模块：

文件处理：
应用上下文初始化：
默认配置定义：
CLI 命令定义：
提交逻辑实现：
CLI 详细程度处理：
GUI 实现：
AI API 提示定义：
AI 提供商注册表：

如果你发现缺少某些内容或不良模式，请随时贡献并进行重构！

代码测试和分析

运行以下命令以运行单元测试、检查类型和检查样式：

./audit.sh

🔧 技术细节

处理的文件类型

Archive Agent 当前支持以下文件类型：

文本：
- 纯文本：.txt, .md
- 文档：
  - ASCII 文档：.html, .htm
  - 二进制文档：.odt, .docx（包括图像）
- PDF 文档：.pdf（包括图像，参见 OCR 策略）
图像：.jpg, .jpeg, .png, .gif, .webp, .bmp

文件处理方式

最终，Archive Agent 将所有内容解码为文本：

纯文本文件解码为 UTF-8。
文档转换为纯文本，提取图像。
PDF 文档根据 OCR 策略进行解码。
图像使用 AI 视觉解码为文本。
- 视觉模型将拒绝无法识别的图像。

使用 Pandoc 处理文档，PyMuPDF4LLM 处理 PDF，Pillow 处理图像。

📌 注意：不支持的文件会被跟踪但不处理。

OCR 策略

对于 PDF 文档，Archive Agent 支持不同的 OCR 策略：

strict OCR 策略：
- 忽略 PDF OCR 文本层。
- 将 PDF 页面视为图像。
- 成本高且速度慢，但更准确。
relaxed OCR 策略：
- 提取 PDF OCR 文本层。
- 解码 PDF 前景图像，但忽略背景图像。
- 成本低且速度快，但准确性较低。
auto OCR 策略：
- 根据从 PDF OCR 文本层提取的字符数为每个页面选择最佳 OCR 策略。
- 根据 ocr_auto_threshold 决定，即 auto OCR 策略解析为 relaxed 而不是 strict 的最小字符数。
- 在成本、速度和准确性之间进行权衡。

请参阅 Archive Agent 设置：ocr_strategy, ocr_auto_threshold

📌 注意：建议使用 strict OCR 策略以获得最佳结果。 PDF 文档通常包含与页面样式/布局相关的小图像，这些图像会增加开销，同时提供的信息很少，甚至会使结果混乱。

💡 提示：启动时会提示你选择 OCR 策略（请参阅运行 Archive Agent）。

智能分块的工作原理

Archive Agent 按以下方式处理解码后的文本：

解码后的文本进行清理并拆分为句子。
句子分组为合理大小的块。
每个块使用 AI 模型拆分为更小的块。
- 优雅处理块边界（最后一个块延续）。
每个块前缀一个 上下文标题（提高搜索效果）。
每个块使用 AI 嵌入转换为向量。
每个向量转换为带有文件元数据的点。
每个点存储在 Qdrant 数据库中。

请参阅 Archive Agent 设置：chunk_lines_block

💡 提示：这种 智能分块 提高了检索的准确性和有效性。

块引用的工作原理

为了确保每个块都能追溯到其来源，Archive Agent 将每个块的文本内容映射到源文件的相应行号或页码。

基于行的文件（例如 .txt）使用行号范围作为引用。
基于页的文件（例如 .pdf）使用页码范围作为引用。

📌 注意：由于分块过程中的段落/句子拆分/合并，引用只是近似的。

块的检索方式

Archive Agent 按以下方式检索与你的问题相关的块：

问题使用 AI 嵌入转换为向量。
从 Qdrant 数据库中检索具有相似向量的点。
仅保留得分足够的点的块。

请参阅 Archive Agent 设置：retrieve_score_min, retrieve_chunks_max

块的重新排序和扩展方式

Archive Agent 过滤检索到的块：

根据与你的问题的相关性对检索到的块进行重新排序。
仅保留最相关的块（其他块丢弃）。
每个选定的块进行扩展以从相关文档中获取更大的上下文。

请参阅 Archive Agent 设置：rerank_chunks_max, expand_chunks_radius

答案的生成方式

Archive Agent 使用重新排序和扩展后的块回答你的问题：

LLM 将块作为问题的上下文接收。
LLM 的答案作为结构化输出返回并格式化。

💡 提示：Archive Agent 使用旨在普遍有用的答案模板。

📄 许可证

本项目采用 GNU GPL v3.0 许可证。

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

详情请参阅 LICENSE。

已知问题

[ ] 虽然 track 最初将文件报告为 已添加，但后续的 track 调用将其报告为 已更改。
[ ] 在跟踪阶段移除并恢复跟踪的文件目前处理不当：
- 移除跟踪的文件会设置 {size=0, mtime=0, diff=removed}。
- 恢复跟踪的文件会设置 {size=X, mtime=Y, diff=added}。
- 由于 size 和 mtime 被清除，我们丢失了检测恢复文件的信息。
[ ] AI 视觉也会应用于空图像，尽管它们可以在本地轻松检测并跳过。
[ ] 由于缺少测试，PDF 矢量图像可能无法按预期转换。（在此期间使用 strict OCR 策略肯定会有帮助。）
[ ] 二进制文档页码（例如 .docx）目前不支持。
[ ] 由于分块过程中的段落/句子拆分/合并，引用只是近似的。
[ ] AI 缓存目前不处理 AiResult 模式迁移。（如果你遇到错误，传递 --nocache 标志或删除所有 AI 缓存文件夹在此期间肯定会有帮助。）
[ ] 在 strict OCR 模式下，从 PDF 页面中拒绝的图像（例如，由于违反 OpenAI 内容过滤策略）目前保持为空，而不是采用从 PDF OCR 层提取的文本（如果有）。

0 条评论
分类：开发

Archive Agent

🚀 ⚡ Archive Agent

🚀 快速开始

Ubuntu / Linux Mint

✨ 主要特性

📦 安装指南

安装要求

Ubuntu / Linux Mint

💻 使用示例

基础用法

跟踪文件

启动 GUI

从命令行提问

高级用法

查看命令列表

创建或切换配置文件

打开当前配置文件的配置

添加包含模式

添加排除模式

删除包含/排除模式

列出包含/排除模式

解析模式并跟踪文件

列出跟踪的文件

列出更改的文件

将更改的文件提交到数据库

组合跟踪和提交

搜索文件

查询文件

启动 Archive Agent GUI

启动 MCP 服务器

📚 详细文档

AI 提供商设置

OpenAI 提供商设置

Ollama 提供商设置

LM Studio 提供商设置

支持的操作系统

如何选择要跟踪的文件

MCP 工具

更新 Archive Agent

Archive Agent 设置

配置文件配置

监视列表

AI 缓存

Qdrant 数据库

开发者指南

重要模块

代码测试和分析

🔧 技术细节

处理的文件类型

文件处理方式

OCR 策略

智能分块的工作原理

块引用的工作原理

块的检索方式

块的重新排序和扩展方式

答案的生成方式

📄 许可证

已知问题

0 个评论

相似服务问题

相关AI产品

热议话题 »