SmartDrive 🧠☁️（智能驾驶系统）

利用RAG架构（结合Pinecone向量搜索和Azure Blob存储），为您的整个OneDrive提供语义搜索功能。

SmartDrive 是一个MCP（模型上下文协议）服务器，它为您的 Microsoft OneDrive 文档带来了智能语义搜索功能。询问Claude查找“税务表格”，它就能为您展示1099表、W-2表及相关文档——即使文件名中并不包含这些确切的词汇。该系统采用真正的RAG（检索增强生成）架构：在Pinecone中进行混合向量搜索（语义+关键词），在Azure Blob中存储完整的文档。

______________________________________________________________________

🔥 特点/功能

核心能力

RAG 架构使用Pinecone中的向量和Azure Blob中的全文进行真正的检索增强生成
混合搜索结合语义（密集向量）+ 关键词（稀疏BM25）以实现最高准确率
语义搜索自然语言查询 - “税表”可找到W-2表、1099表等。
灵活嵌入选择本地（免费）、Voyage AI（推荐）、Pinecone 推理或 OpenAI 兼容 API
每个文件一个向量无分块处理 = 索引速度提升12.5倍，搜索更简单，结果更佳
10万字符嵌入表示嵌入完整小文档，对大文件进行智能采样（80%开头 + 20%结尾）
增量同步智能检测未更改文件 - 仅索引新/修改过的内容
交互式文件夹选择选择要索引的文件夹，跳过不需要的文件夹
智能缓存在运行之间记住身份验证和文件夹选择
MCP集成两个适用于Claude Desktop的工具： search_onedrive 并且 read_document

文档支持

文件PDF（扫描文档含OCR识别功能！）、DOCX、DOC
演示文稿PPTX（旧版.ppt格式不支持 - 请转换为.pptx）
电子表格XLSX，XLSM，CSV
数据JSON，TXT，Markdown（MD）
图片PNG、JPG、TIFF、BMP、GIF（带OCR功能）
档案ZIP 文件（列出内容或解压并建立索引）
优雅的降级（或回退）仅对元数据进行了索引的损坏/格式错误文件

光学字符识别（OCR）与文档智能

本地OCR（光学字符识别）适用于扫描PDF和图像的EasyOCR（免费，无需外部软件！）
云端OCR（光学字符识别）Azure 计算机视觉，实现10-20倍更快的处理速度（可选）
Azure 文档智能服务高级AI，支持手写识别的表单、表格、发票和收据处理
灵活模式从“从不”、“选择性（智能检测）”到“始终”使用文档智能功能
无需设置本地OCR开箱即用
智能检测自动检测扫描的PDF文件并应用OCR（光学字符识别）

______________________________________________________________________

📦 安装

先决条件

Python 3.10及以上版本
带有OneDrive的Microsoft 365账户
Azure 帐户（用于 Blob 存储 - 提供免费层级）
Pinecone账户（提供免费层级，支持混合搜索）
Claude Desktop（中文可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”）

快速设置

克隆仓库

   git clone https://github.com/1818TusculumSt/smartdrive-mcp.git
   cd smartdrive-mcp

安装依赖项

   pip install -r requirements.txt

创建Azure应用程序注册

- 首选 Azure 门户 → 应用程序注册 → 新注册 - 姓名： SmartDrive MCP - 支持的账户： 仅限个人微软账户 - 重定向URI：留空 - 创建后，前往 API权限 → 添加： - Files.Read.All - User.Read - 首选认证 → 启用 允许公共客户端流量 - 复制 应用程序（客户端）ID 并且 目录（租户）ID

创建Pinecone索引

选项A：手动创建（推荐给大多数用户）

- 首选松果 → 创建索引 - 名字： smartdrive - 尺寸：根据您的嵌入服务提供商进行选择： - 384 用于本地（全MiniLM-L6-v2） - 1024 用于Pinecone推理（llama-text-embed-v2） - 2048 为Voyage AI（voyage-3-large，推荐） - 指标： cosine - 云服务：AWS（提供免费套餐） - 地区：选择离您最近的（例如。， us-east-1) - 重要的勾选“启用混合搜索”以获得最佳结果（结合语义搜索+关键词搜索） - 复制你的 API 密钥 并且 索引主机 创建之后

选项B：自动化创建（高级用户）

   # Configure your .env with Pinecone credentials first
   python create_hybrid_index.py

- 自动生成针对Voyage AI优化的混合搜索索引 - 使用2048维和点积度量 - 删除并重新创建现有索引（谨慎使用！） - 适用于紧急恢复或脚本化部署

创建 Azure Blob 存储容器

- 首选 Azure 门户 → 存储帐户 → 创建新的（或使用现有的） - 选择标准性能层级（通用用途 v2） - 创建后，前往 访问密钥 → 复制 连接字符串 - 创建一个名为……的容器 documents （或者使用你自己的名字）

配置 .env

复制 .env.example to .env 并填写您的价值观：

   # Pinecone (required)
   PINECONE_API_KEY=your_pinecone_api_key
   PINECONE_INDEX_NAME=smartdrive
   PINECONE_HOST=smartdrive-xxxxx.svc.aped-xxxx-xxxx.pinecone.io

   # Microsoft (required)
   MICROSOFT_CLIENT_ID=your_azure_client_id
   MICROSOFT_TENANT_ID=consumers

   # Azure Blob Storage (required for RAG)
   AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
   AZURE_STORAGE_CONTAINER_NAME=documents

   # Embedding provider (optional, default: local)
   EMBEDDING_PROVIDER=local
   EMBEDDING_MODEL=all-MiniLM-L6-v2

   # For Voyage AI (recommended - 32K token context, 2048 dims, $0.10/1M tokens):
   # EMBEDDING_PROVIDER=voyage
   # VOYAGE_API_KEY=your_voyage_api_key
   # VOYAGE_MODEL=voyage-3-large

   # Azure Computer Vision OCR (optional - 10-20x faster than local)
   # AZURE_VISION_KEY=your_azure_vision_key
   # AZURE_VISION_ENDPOINT=https://your-region.api.cognitive.microsoft.com/

为您的OneDrive创建索引

   python onedrive_crawler.py

您将看到一个交互式菜单：

   ============================================================
   📋 SmartDrive Crawler - Main Menu
   ============================================================
   1. Run crawler (use cached folder choices)
   2. Reset folder choices and start fresh
   3. View/edit cached folder choices
   4. Exit

- 首次使用：选择选项1 - 使用您的 Microsoft 帐户进行身份验证（设备代码流程） - 选择ZIP处理方式（列出内容或解压 - 默认为列出） - 设置文件限制（或按 Enter 键不限制以索引所有内容） - 对于爬虫发现的每个文件夹，回答“是”或“否” - 使用“总是是”或“总是跳过”来记住您的选择！

添加到Claude桌面版

编辑 %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)：

   {
     "mcpServers": {
       "smartdrive": {
         "command": "python",
         "args": [
           "C:\\path\\to\\smartdrive-mcp\\smartdrive_server.py"
         ],
         "env": {
           "PINECONE_API_KEY": "your_pinecone_api_key",
           "PINECONE_INDEX_NAME": "smartdrive",
           "PINECONE_HOST": "smartdrive-xxxxx.svc.aped-xxxx-xxxx.pinecone.io",
           "AZURE_STORAGE_CONNECTION_STRING": "DefaultEndpointsProtocol=https;AccountName=...",
           "AZURE_STORAGE_CONTAINER_NAME": "documents"
         }
       }
     }
   }

注MCP服务器仅需要Pinecone和Azure Blob Storage的凭据。爬虫还需要额外的凭据（Microsoft Graph API、OCR服务、嵌入式API密钥）。

重启Claude桌面版

______________________________________________________________________

🐳 Docker 安装设置（推荐）

为什么选择Docker？

✅ 零系统污染 - 隔离环境
✅ 无依赖冲突 - 包含所有Python包
✅ 可重复的 - 在任何地方都功能一致
✅ 易于清洁 - 移除容器，完成
✅ 持久缓存 - OAuth令牌和文件夹选择在重启后仍然保留

Docker 快速入门

克隆并配置

   git clone https://github.com/1818TusculumSt/smartdrive-mcp.git
   cd smartdrive-mcp
   cp .env.example .env
   # Edit .env with your credentials

构建并运行

   docker-compose up -d

首次为您的OneDrive创建索引

   docker-compose run --rm smartdrive-mcp python onedrive_crawler.py

后续运行 （使用缓存的文件夹选择）

   docker-compose run --rm smartdrive-mcp

Docker 命令

# Build the image
docker-compose build

# Run crawler interactively
docker-compose run --rm smartdrive-mcp

# View logs
docker-compose logs -f

# Stop container
docker-compose down

# Rebuild after code changes
docker-compose build --no-cache

# Clean up everything (keeps .env and cache files)
docker-compose down --rmi all

缓存持久化

Docker 会自动从您的主机挂载这些缓存文件：

~/.smartdrive_token_cache.json - OAuth令牌（重启后仍有效）
~/.smartdrive_folder_skip_cache.json - 文件夹选择（记住跳过/处理的决定）
~/.EasyOCR/ - OCR模型（避免重新下载100MB）

与Claude Desktop配合使用

将Claude桌面指向Docker容器的MCP服务器：

{
  "mcpServers": {
    "smartdrive": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/path/to/smartdrive-mcp/.env",
        "smartdrive-mcp",
        "python",
        "smartdrive_server.py"
      ]
    }
  }
}

______________________________________________________________________

🚀 使用方法

在Claude Desktop中

SmartDrive 提供了两种 MCP 工具供 Claude 使用：

1. search_onedrive - 混合语义+关键词搜索

使用密集（语义）+稀疏（BM25/关键词）向量在Pinecone中进行搜索
返回包含文件路径、日期、分数和内容预览的前k个结果
自动从Azure Blob中获取匹配文档的全文
智能截断确保响应大小不超过900KB（每文档显示前2000个字符）

2. read_document - 检索完整文档文本

从Azure Blob存储中获取完整的文档内容 doc_id
当你需要搜索结果的全文时，请使用此功能
返回整个文档（不截断）

只需向Claude提出自然语言问题：

“在我的OneDrive中搜索简历”
“查找2024年的税务文件”
“给我看看项目提案”
“我第四季度预算的会议记录在哪里？”
“读取文档 doc_abc123 的全部内容”（在从搜索结果中获取 doc_id 后）

克劳德将自动使用 search_onedrive 查找相关文件，并且可以使用 read_document 在需要时检索完整内容。

交互式爬虫菜单

该爬虫具备完整的菜单系统，用于管理您的索引：

选项1：运行爬虫

选择ZIP文件处理方式（列出内容或提取内容）
设置文件限制（或对于完整索引无限制）
交互式文件夹选择
通过OCR状态实现美观的进度跟踪

选项2：重置文件夹选择

清除所有缓存的文件夹偏好设置
重新开始选择文件夹

选项3：查看/编辑缓存文件夹选项

查看所有已保存的文件夹选择
在SKIP和PROCESS文件夹之间切换
删除特定的缓存选项

处理概要

爬取完成后，您将获得一份详细的摘要：

============================================================
📊 Processing Summary:
============================================================
✅ Successfully extracted: 847 files

❌ Failed extractions (3):
   • corrupted_report.xlsx (.xlsx)
   • malformed_doc.pdf (.pdf)

⚠️ Unsupported file types (5):
   • .mp4: 2 file(s)
   • .zip: 3 file(s)
============================================================

______________________________________________________________________

🏗️ 建筑

SmartDrive采用了一种 真正的RAG（检索增强生成）架构 该技术将向量嵌入与文档存储分离，以实现最佳性能并支持无限大的文档尺寸。

┌─────────────────┐
│  Claude Desktop │
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────────┐       ┌──────────────────┐
│ smartdrive_server.py│◄──────┤  Pinecone Index  │
│  (MCP Server)       │       │ (Hybrid Vectors) │
└────────┬────────────┘       └──────────────────┘
         │                             │
         │                             ├─ Dense vectors (semantic)
         │                             ├─ Sparse vectors (BM25/keyword)
         │                             ├─ Minimal metadata
         │                             └─ doc_id references
         │
         └──► ┌──────────────────┐
              │  Azure Blob      │
              │  (Full Texts)    │
              └──────────────────┘
                      ├─ Complete documents
                      ├─ Unlimited size
                      └─ Fast retrieval (~50ms)

它是如何工作的

1. 索引编制（onedrive_crawler.py）

当你运行爬虫程序时，对每个OneDrive文件会执行以下操作：

认证通过Microsoft Graph API（设备代码流，缓存）
爬取OneDrive 递归执行，支持交互式文件夹选择
提取文本 来自文件：

- PDFs（Portable Document Format files，便携式文档格式文件）PyMuPDF（fitz）直接提取文本 - 扫描的PDF/图片使用Azure文档智能进行OCR → Azure计算机视觉 → 作为备选的EasyOCR链 - 办公文档python-docx（用于处理DOCX文件），python-pptx（用于处理PPTX文件），openpyxl（用于处理XLSX文件） - 文本文件直接读取（TXT、JSON、MD、CSV） - 档案列出或提取ZIP文件内容

生成嵌入表示：

- 稠密向量可配置提供者（本地/Voyage AI/Pinecone/OpenAI兼容API） - 稀疏向量用于关键词匹配的BM25编码器（自动截断至2048个术语） - 最多可嵌入10万个字符（智能采样：对于大文件，取开头的80% + 结尾的20%）

存放在两个地方:

- Azure Blob 存储完整文档文本 → 返回 doc_id （文件路径的SHA256哈希值） - 松果密集向量 + 稀疏向量 + 最小元数据 + doc_id 参考

增量同步检查Pinecone的元数据（修改日期+大小）以跳过未更改的文件
清理从Pinecone中移除过期的向量，并从Azure中移除孤立的二进制大对象（blobs）

2. 搜索（smartdrive_server.py）

当克劳德通过MCP搜索您的OneDrive时：

查询嵌入将自然语言查询转换为密集向量+稀疏向量
混合搜索使用两个向量在Pinecone中进行语义+关键词匹配查询
检索比赛（或匹配项）获取前k个结果 doc_id 以及元数据
获取全文从Azure Blob中检索完整文档 doc_id
智能截断每条结果预览前2000个字符，保持总响应大小小于900KB
回到克劳德格式化结果，包含文件路径、日期、分数和内容

组件

核心文件：

smartdrive_server.py 翻译为中文是：“智能驱动服务器.py”（或根据具体上下文，也可译为“智能存储服务器.py”等，但“智能驱动服务器”是较为通用的翻译） - MCP服务器暴露 search_onedrive 和 read_document 工具
onedrive_crawler.py 翻译为中文是：“OneDrive 爬虫脚本.py” 或者 “用于 OneDrive 的爬取程序.py”。这里，“crawler”通常指的是用于自动抓取或收集数据的程序或脚本，而“OneDrive”是微软提供的云存储服务 - 索引脚本：爬取OneDrive，提取文本，生成嵌入向量，存储在Pinecone + Azure Blob中
embeddings.py（可译为“嵌入.py”，但通常直接保留原名，因为“embeddings.py”在技术语境下已具有明确含义，即“用于处理嵌入表示的Python脚本文件”） - 嵌入式提供者抽象（本地/Voyage/Pinecone/OpenAI兼容API）
document_storage.py 翻译为中文是：“文档存储.py”（或可理解为“用于文档存储的Python脚本/模块”） - 用于完整文档文本的Azure Blob存储接口
document_intelligence.py 翻译为中文是：“文档智能.py” - 集成Azure Document Intelligence以实现高级表单/表格提取
config.py（配置文件） - 使用 pydantic-settings 进行配置管理

依赖项：

松果混合搜索（密集向量+稀疏向量）的向量数据库
Azure Blob 存储文档存储（全文，大小不限）
Microsoft Graph APIOneDrive文件访问（设备代码流认证）
PyMuPDF（fitz）PDF文本提取
python-docx，python-pptx，openpyxl办公文档解析
EasyOCR本地OCR备用方案（基于CPU，每页约10-30秒）
Azure 计算机视觉 （可选）：云端OCR（速度提升10-20倍，每页约1-3秒）
Azure 文档智能 （可选）：高级表单/表格提取
sentence-transformers（句子转换器）局部嵌入模型（默认：all-MiniLM-L6-v2）
松果文（或译为松果文本）用于稀疏向量（关键词匹配）的BM25编码器

关键架构决策

为什么使用RAG（向量与全文分离）？

✅ 对/正确/确认 无元数据限制Pinecone有40KB的元数据上限，Azure Blob存储空间无限制
✅ 每个文件一个向量不进行分块处理 = 索引速度提升12.5倍，搜索更简单
✅ 全文上下文检索搜索找到相关文档，然后检索完整文本
✅ 成本效益高Azure存储 vs 昂贵的向量元数据：仅需约0.02美元/GB/月

为什么采用混合搜索（密集+稀疏）？

✅ 稠密向量语义理解（“税务表格”匹配“W-2”、“1099”）
✅ 稀疏向量精确关键词匹配（文件名搜索、缩写）
✅ 翻译为中文是：✅（这个符号本身在中文中通常表示“正确”或“确认”，但直接翻译时保持原样，因为它是通用符号）。如果要解释其含义，可以说：“✅ 表示正确或确认”。 更高的准确性结合语义相似度与关键词精确度

为什么选择10万个字符嵌入？

✅ 全面理解文档小型文档整体嵌入，大型文档智能采样
✅ 无分块开销1个向量 vs 每个文件10多个
✅ 更快的搜索需要查询的向量更少
✅ 更多上下文Voyage AI支持32K个标记（128K个字符），我们为了效率使用了100K

为什么选择增量同步？

✅ 速度跳过未更改的文件（重新索引速度提升约100倍）
✅ 成本节约不重新嵌入未更改的文档
✅ 元数据比较在提取之前，检查Pinecone中的修改日期+文件大小

______________________________________________________________________

🛠️ 配置

嵌入提供者

SmartDrive支持四种嵌入式提供商：

本地（免费，私密）

EMBEDDING_PROVIDER=local
EMBEDDING_MODEL=all-MiniLM-L6-v2

✅ 在您的机器上运行（使用sentence-transformers）
✅ 无需API调用或产生费用
✅ 完全隐私
📊 384维，约512个标记（token）的上下文长度

Voyage AI（推荐用于处理大型文档）🚀

EMBEDDING_PROVIDER=voyage
VOYAGE_API_KEY=your_voyage_api_key
VOYAGE_MODEL=voyage-3-large

✅ 32,000个标记的上下文 (128K字符) - 嵌入整个50多页的PDF文件！
✅ 2048维 以获得最佳品质
快速云API，针对长文档优化
💰（表示金钱或货币的符号） 每100万个代币0.10美元 （对于600个典型文件，费用约为0.10-0.50美元）
🎯 最适合用于：学术论文、书籍、报告、大型文档

松果推理（或“松果推断”）

EMBEDDING_PROVIDER=pinecone
EMBEDDING_MODEL=llama-text-embed-v2

通过Pinecone托管嵌入模型
1024维（高质量）
需要Pinecone API密钥
获取专业模型的途径

自定义API

EMBEDDING_PROVIDER=api
EMBEDDING_API_URL=https://your-api.com/embeddings
EMBEDDING_API_KEY=your_api_key
EMBEDDING_MODEL=your-model-name

OpenAI兼容的API格式
使用任何嵌入服务（如OpenAI、Cohere等）
支持自托管选项

增量同步

SmartDrive智能跳过未更改的文件，以节省时间和API成本：

✅ 预提取检查在下载/解压文件前检查Pinecone
✅ 元数据比较比较文件的修改日期和大小
✅ 跳过未更改项未更改的文件将被完全跳过
✅ 仅更新修改过的部分仅重新索引已更改的文件
⚡（闪电符号，常用于表示快速、电、能量等概念，在中文中无直接对应文字，可保持原样或根据上下文意译） 快100倍左右 用于重新索引大多未更改的文件夹

新文件夹检测在使用缓存的文件夹选择运行时，您可以选择检查新文件夹：

按回车键 = 跳过检查（快速，仅使用缓存）
类型“检查”= 发现新文件夹并逐一提示

OCR配置

SmartDrive支持两种OCR方法：

本地OCR（EasyOCR - 默认）

免费并且开箱即用
首次使用时自动下载模型（约100MB）
速度每页10-30秒
无外部依赖

云OCR（Azure计算机视觉 - 可选）

添加到你的 .env：

AZURE_VISION_KEY=your_azure_vision_key
AZURE_VISION_ENDPOINT=https://your-region.api.cognitive.microsoft.com/

好处：

快10到20倍每页1-3秒 vs 10-30秒
更准确的OCR识别结果
您的机器上没有CPU/GPU负载
免费层级/免费套餐每月5000页
付费层级每1,000页1.50美元（典型使用情况下约为0.50美元至2美元）

设置：

首选 Azure 门户
创建“计算机视觉”资源
选择“免费F0”层级（每月5,000页）或“标准S1”层级
复制您的API密钥和终端节点到 .env

OCR 严格模式（可选）

仅强制使用 Azure OCR（不回退到 EasyOCR）：

OCR_STRICT_MODE=true

当启用时：

✅ 仅使用Azure OCR（速度快10-20倍）
❌ 如果Azure OCR失败，则文件处理失败（没有慢速的EasyOCR回退机制）
💡 当你有Azure信用额度时，用这个来提速

如果提供了凭据，SmartDrive 将自动使用 Azure OCR；否则，将回退到本地的 EasyOCR（除非启用了严格模式）。

Azure 文档智能（高级版）

Azure Document Intelligence（原名Form Recognizer）是一项高级AI服务，提供了超越基础OCR的高级提取功能。它专为结构化文档设计，如表格、发票、收据和税务文件等。

它的功能：

智能表单提取自动识别并提取表单中的键值对
表格提取保持表格结构，包括行、列和单元格之间的关系
手写识别准确识别手写文本
布局分析理解文档结构（标题、章节、段落）
预构建模型针对发票、收据、税务表格、身份证件进行了优化

三种操作模式：

never （默认）文档智能功能已禁用

- 使用标准Azure OCR → EasyOCR回退链 - 对于简单文件，这是最快且最经济的方式

selective （智能检测）为特定文档类型自动启用

- 当文件名包含关键字时激活： tax， invoice， receipt， form， w2， 1099， w-2， 1040 - 成本与能力的完美平衡 - 推荐用于混合文档库

always对所有文档使用文档智能技术

- 每个文件的最大提取质量 - 成本更高 - 仅当您需要对所有文档进行高级提取时才使用

定价与限制：

免费套餐（F0）：

成本免费
局限性仅处理（进程） 前两页 多页文档的
月度限额每月500页
速度每秒1笔交易（TPS）
最适合于测试、小文档集或1-2页的文档

标准层（S0）：

成本： 每1000页1.50美元
完整的文档处理所有页面已提取，无页数限制
无月度限制按使用付费
速度15 TPS（每秒事务处理量）
典型成本每500页收费约0.75美元（相比免费层级的前2页限制）
推荐用于生产环境使用，多页文档

设置说明：

首选 Azure 门户
创建一个 “Document Intelligence”翻译成中文是“文档智能” 资源（或搜索“表单识别器”）
选择层级：

- 自由F0仅测试或1-2页的文档 - 标准S0在生产环境中使用，实现完整文档提取

创建后，前往 “密钥和终端点”
复制 密钥1 并且 终端点URL
添加到你的 .env：

AZURE_FORM_RECOGNIZER_KEY=your_key_here
AZURE_FORM_RECOGNIZER_ENDPOINT=https://your-region.cognitiveservices.azure.com/

# Choose your mode:
USE_DOCUMENT_INTELLIGENCE=selective  # never, selective, or always

备用链：

SmartDrive采用了一套精密的备用系统：

Azure 文档智能服务 （如果已启用且条件满足）
Azure 计算机视觉 OCR（光学字符识别） （如果提供了凭据）
EasyOCR （本地，随时可用）

演出

处理时间每份文件5-15秒（根据页数和复杂程度而有所不同）
超时2分钟安全超时机制防止在问题文件上卡住
进度指示器多页文档的实时逐页进度显示
可靠性如果服务不可用或超时，则自动回退

最佳用例：

税务文件（W-2表、1099表、1040表）
具有复杂布局的发票和收据
具有结构化字段的业务表格
带有表格和签名的合同
手写笔记和表格
需要精确提取表格的文档

提示：

从……开始 selective 平衡成本与质量的模式
使用 always 仅当您需要对每份文档进行高级提取时，才使用此模式
免费版（F0）适合测试，但生产环境中的多页文档建议升级到S0版
在Azure门户中监控您的使用情况，以确保不超出预算

索引定制

文件限制：

先用50-100个文件进行测试
然后按回车键以无限制地索引所有内容

文件夹选择：

每个文件夹的交互式提示
使用“始终”选项来缓存您的选择
随时通过菜单（选项3）编辑选择

ZIP 文件处理：

默认：列出内容（快速，可通过文件名和文件列表搜索）
提取：从ZIP文件中的文件提取全文（速度较慢，但全面）

______________________________________________________________________

📊 支持的文件格式

类别	格式	OCR支持
文档	PDF, DOCX, DOC	✅（扫描版PDF）
演示文稿	PPTX	-
电子表格	XLSX, XLSM, XLTX, XLTM, CSV	-
数据	JSON、TXT、Markdown（MD）	-
图像	PNG、JPG、JPEG、TIFF、BMP、GIF	✅
档案	ZIP	列表或解压

注：不支持旧版PowerPoint（.ppt）文件。请转换为.pptx格式以进行全文提取。

______________________________________________________________________

🎯 最佳实践

对于大型OneDrive库（10GB及以上）

先测试以100个文件为限制开始
明智地选择文件夹跳过临时文件夹、下载文件等。
ZIP策略对大多数ZIP文件使用“列表”模式（更快）
通宵运行大型图书馆的全面索引可能需要数小时
监控进度OCR 显示逐页进行的进度

为了获得最佳搜索结果

描述性查询“查找第四季度的项目提案”比“查找提案”效果更好
利用上下文包含时间范围、主题或人名
迭代搜索根据初步结果进行细化

维护您的索引

定期重新运行每月运行爬虫以抓取新文件
缓存的选择您的文件夹偏好设置已保存
增量更新未来版本将支持智能同步

______________________________________________________________________

🐛 故障排除

常见问题

“OCR失败”警告

对于某些扫描的PDF文件来说，这是预期之中的情况
文本提取会采用任何可用的方法
大多数文档都能正常工作

Excel解析错误

一些复杂的XLSX文件可能会失败
CSV格式的数据文件更可靠

认证超时

令牌已被缓存 - 如过期，请重新运行
删除 ~/.smartdrive_token_cache.json 强制重新认证

处理速度慢

OCR每页处理时间为3-10秒
扫描文档的正常状态
进度指示器显示正在工作

需要帮助吗？

在GitHub上创建一个议题，内容为：

错误信息（如有）
导致问题的文件类型
复现步骤

______________________________________________________________________

🗺️ 路线图

已完成 ✅

核心功能：

✅ 递归文件夹爬取，支持交互式选择
✅ 带缓存的交互式文件夹选择
✅ 新文件夹检测（可选的预抓取检查）
✅ 增量同步（提取前Pinecone检查）
✅ 微软身份验证的令牌缓存
✅ 进度指示器和全面的错误报告
✅ 对损坏文件的优雅降级处理

文件格式支持：

✅ 文件格式：PDF、DOCX、DOC
✅ 电子表格：XLSX，XLSM，CSV
✅ 数据格式：JSON、TXT、Markdown（.md）
✅ 图像格式：PNG、JPG、TIFF、BMP、GIF（含OCR）
✅ 存档：ZIP（列表+提取模式）

光学字符识别（OCR）与文档智能：

✅ 本地OCR（EasyOCR）支持自动下载模型
✅ 使用云OCR（Azure计算机视觉）实现10-20倍加速
✅ Azure 文档智能服务，支持三种模式（从不/选择性/始终）
✅ 带逐页进度的扫描PDF OCR（光学字符识别）
✅ 通过文档智能实现图像OCR（支持所有格式）
✅ 智能超时处理（2分钟安全机制）
✅ OCR 严格模式（仅适用于 Azure，无回退选项）

RAG架构：

✅ 真正的RAG（检索增强生成）实现Pinecone中的向量，全文存储在Azure Blob Storage中
✅ 翻译为中文是：✅（这个符号本身在中文中通常不直接翻译，但可以理解为“正确”或“已确认”的意思，具体根据上下文而定。） 每个文件一个向量 （无分块处理，上传速度提升12.5倍）
✅ 10万个字符嵌入向量 （小文档全部处理，大文档智能抽样）
✅ 2048维度之旅AI 用于最高质量的嵌入（可配置：384/1024/2048）
✅ 混合搜索稠密（语义）+ 稀疏（BM25/关键词）向量
✅ 丰富的元数据文件类型分类、大小、日期、覆盖范围指标
✅ Azure Blob 存储无限文档大小存储（约0.02美元/GB/月）
✅ 智能清理从Pinecone和Azure中移除过期文档
✅ 防重复（或防止重复）Azure在上传前检查是否存在
✅ 稀疏向量处理自动截断至2048项（Pinecone限制）
✅ 两种MCP工具： search_onedrive (混合搜索) + read_document （全文检索）
✅（勾选标记，通常表示正确、确认或完成） 智能结果截断保持响应大小在900KB以下，以避免MCP 1MB限制问题

嵌入提供者：

✅ 本地嵌入（sentence-transformers，免费）
✅ 旅行AI（32K个标记上下文，2048维，针对长文档优化）
✅ Pinecone 推理（llama-text-embed-v2，1024 维）
✅ 自定义API（兼容OpenAI的端点）

即将上线🚀

增量同步守护进程（高优先级）

一个用于自动索引更新的真实后台服务：

Microsoft Graph Delta API（微软图谱增量API）仅检测已更改的文件（新增/更新/删除）
持续后台进程全天候24小时运行，每5-10分钟检查一次
智能状态追踪存储deltaLink代币以追踪自上次同步以来的变化
删除处理自动从Pinecone中移除已删除文件的向量
高效处理仅索引变化内容 - 不进行完整重新爬取
合适的守护进程不是一个计划任务脚本 - 真正的后台服务，带有日志记录功能
估计的复杂度3-4小时的实现（增量API使得这出乎意料地可行）
结果真正的“设置即忘”——您的索引自动保持最新

其他特性

\[ \] 开放WebUI集成
\[ \] 对SharePoint/Teams文件的支持
\[ \] 可配置的抓取深度
\[ \] 自定义元数据提取
\[ \] 多语言OCR

______________________________________________________________________

🤝 贡献（或“参与贡献”）

由社区为社区而建。欢迎提交拉取请求（PR）！

我们希望获得帮助的领域：

性能优化
增量同步实现
Open WebUI 集成
文档改进
单元测试
其他文件格式（例如，RTF、ODT）

______________________________________________________________________

📄 许可证

MIT许可证——你可以随意使用这个，只需保持其免费且可访问。

______________________________________________________________________

🙏 致谢

使用……构建 MCP（Minimum Cost Path，最小成本路径）由Anthropic开发
通过嵌入（的方式） sentence-transformers（句子转换器）
向量存储由松果
Microsoft Graph API用于访问OneDrive
由OCR技术提供支持 EasyOCR（易OCR）
通过PDF处理 PyMuPDF（中文可译为“Python MuPDF”或保持原名，因其是一个Python库，专门用于处理PDF文件）

______________________________________________________________________

💬 支持

有问题吗？有难题吗？请在GitHub上提交一个议题或联系我们。

由🔥热情打造，出自 @1818TusculumSt（直接翻译为中文地址形式可保持原样，若需意译则为“@1818 Tusculum街”）

______________________________________________________________________

💰 成本明细

免费套餐设置（推荐用于测试）：

✅ 表示正确、确认或完成。 嵌入（或嵌入表示）本地（sentence-transformers）- 每月0美元
✅ 松果免费层级 - 10万条向量，支持混合搜索 - 每月0美元
✅ Azure Blob 存储免费层级 - 5GB存储空间，每月20K次读取操作 - 每月0美元
✅ OCR（光学字符识别）本地EasyOCR - 每月0美元（速度较慢但免费）
总计每月0美元，适用于中小型OneDrive库（\<1000个文件）

生产设置（建议用于大型库）：

💰（货币符号，中文中通常直接使用该符号表示货币，不需翻译） 嵌入（或表示）Voyage AI - 600个典型文件的索引费用约为0.10-0.50美元（一次性费用）
💰（金钱符号，无直接对应中文含义，通常表示钱或金钱）松果无服务器 - 每10万个向量每月约0.03美元（按使用量付费）
💰（钱的符号，无具体中文含义，可理解为“钱”或“金钱”） Azure Blob 存储约0.02美元/GB/月（约0.02美元/月，适用于500份文档，平均每份50KB）
💰（金钱符号，无具体含义，可理解为“钱”或“金钱”） OCR（Optical Character Recognition）即光学字符识别 （可选）：Azure 计算机视觉 - 免费层级：每月5000页，付费：每1000页1.50美元
总计典型使用情况（1000-5000个文件）的费用为每月约0.50-2.00美元

降低成本的小贴士：

如果你不需要32K个token的上下文，可以使用本地嵌入（免费）而不是Voyage AI
Azure Blob 免费套餐涵盖了大多数个人使用场景（5GB = 约10万份文档）
Pinecone免费套餐支持高达10万个向量（对于个人OneDrive来说绰绰有余）
本地EasyOCR免费但速度慢——只有在您有大量扫描文档时才使用Azure OCR

Smartdrive MCP

快速接入

详细介绍

SmartDrive 🧠☁️（智能驾驶系统）

🔥 特点/功能

核心能力

文档支持

光学字符识别（OCR）与文档智能

📦 安装

先决条件

快速设置

🐳 Docker 安装设置（推荐）

Docker 快速入门

Docker 命令

缓存持久化

与Claude Desktop配合使用

🚀 使用方法

在Claude Desktop中

交互式爬虫菜单

处理概要

🏗️ 建筑

它是如何工作的

组件

关键架构决策

🛠️ 配置

嵌入提供者

本地（免费，私密）

Voyage AI（推荐用于处理大型文档）🚀

松果推理（或“松果推断”）

自定义API

增量同步

OCR配置

本地OCR（EasyOCR - 默认）

云OCR（Azure计算机视觉 - 可选）

OCR 严格模式（可选）

Azure 文档智能（高级版）

索引定制

📊 支持的文件格式

🎯 最佳实践

对于大型OneDrive库（10GB及以上）

为了获得最佳搜索结果

维护您的索引

🐛 故障排除

常见问题

需要帮助吗？

🗺️ 路线图

已完成 ✅

即将上线🚀

增量同步守护进程（高优先级）

其他特性

🤝 贡献（或“参与贡献”）

📄 许可证

🙏 致谢

💬 支持

💰 成本明细

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP