Skip to content

a607ernie/parse_unstructured

BranchesTags

Repository files navigation

Parse Unstructured — 非結構化文件 Pipeline + MCP Server

將混亂的企業文件（PDF/PPTX/DOCX/XLSX/MD/TXT）轉換為可搜尋的結構化知識庫，並透過 MCP Protocol 提供 API。

目的

企業內部大量文件（財報、roadmap、SOP、合約、報表）以多種格式散落各處，無法被 LLM 直接使用。此專案提供一條完整的處理鏈：

PDF/PPTX/DOCX/XLSX/MD/TXT  →  Extract  →  Clean  →  Chunk  →  BM25 Index  →  MCP Server

讓任何 MCP client（Claude Desktop、自訂 agent）都能以自然語言搜尋這些文件內容。

功能

  • 多格式解析：PDF（pdfplumber）、PPTX（python-pptx）、DOCX（python-docx）、XLSX（openpyxl）、MD、TXT
  • PDF 表格：保留結構，轉為 Markdown table
  • PPTX 備註：支援 speaker notes 提取
  • DOCX 章節分割：依標題層級將文件分割為節
  • XLSX 工作表：每工作表為一節，資料轉 Markdown 表格
  • MD/TXT 段落分割：依標題或空白行分割
  • 雜訊清洗：自動去除企業文件常見 boilerplate（CONFIDENTIAL、版權等）
  • Token-aware chunking：langchain RecursiveCharacterTextSplitter + tiktoken，以 token 計數切割，按段落→行→空格→字元優先順序確保語義邊界，支援 overlap
  • Hybrid 搜尋（BM25 + Vector）：預設 RRF fusion 融合關鍵字精準度與語意相似性；無 ONNX 模型時自動降級為純 BM25
  • ONNX Embedding 引擎：BGE small ZH v1.5 轉 ONNX，CPU 推論 512-dim 向量，無 PyTorch 依賴
  • MCP Server：支援 HTTP（SaaS 外部連線）和 stdio 兩種 transport，內建 CORS 與 Bearer token 驗證
  • 跨 session 持久化：upload_document 同步加入共享 KB；server 重啟後自動從 ChromaDB 恢復已上傳文件，search_knowledge_base 持續可查
  • 結構化日誌：所有操作（上傳、解析、搜尋）均寫入 logs/app.log，每日輪換、保留 3 天，支援 LOG_LEVEL 環境變數

Claude Code Skills

本專案提供兩個 Claude Code Skill，涵蓋「本地離線前處理」與「完整 MCP RAG 流程」兩種使用情境。

Skill 1：doc-preprocessor-internal（主專案內離線解析）

使用主專案 pipeline/ 模組，不需要 MCP Server 即可將文件解析為 Markdown。

# PDF → data/Q3_Financial_Report.md
echo '{"file_path": "data/Q3_Financial_Report.pdf", "doc_type": "pdf"}' \
  | python3 .claude/skills/doc-preprocessor-internal/run.py
項目 說明
位置 .claude/skills/doc-preprocessor-internal/
合約 stdin JSON → .md 檔案 + stdout JSON（執行結果）
執行邊界 唯讀輸入、寫入一個 .md 檔案、無網路、最大 50MB、60 秒
輸出 {status, file, pages_or_slides, output_file}
支援格式 PDF、PPTX、DOCX、XLSX、MD、TXT

Skill 2：mcp-rag-pipeline（完整 E2E RAG）

上傳文件至 MCP Server → BM25 搜尋 → 回傳 LLM-ready context → 自動清理，一次呼叫完成完整 RAG 流程。

前置條件：MCP Server 須已啟動（python3 mcp_server.py）

# 基本用法
echo '{"file_path": "data/Q3_Financial_Report.pdf", "query": "Q3 的主要財務指標"}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py

# 指定回傳 chunk 數
echo '{"file_path": "data/Product_Roadmap.pptx", "query": "產品路線圖重點", "top_k": 3}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py

# 透過環境變數指定 server
export MCP_URL=http://my-server:8000/mcp
export MCP_API_KEY=my-secret
echo '{"file_path": "report.pdf", "query": "主要結論"}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py
項目 說明
位置 .claude/skills/mcp-rag-pipeline/
合約 stdin JSON → MCP tools → stdout JSON
執行邊界 唯讀本地檔案、連線 MCP Server、自動 cleanup、最大 50MB
輸出 {context: "...", results: [...], doc_removed: true}
支援格式 PDF、PPTX、DOCX、XLSX、MD、TXT

mcp-rag-pipeline 測試範例（6 種格式）

需先啟動 MCP Server：python mcp_server.py

# PDF — 財務報告查詢合併營收
echo '{"file_path": "data/test_report.pdf", "query": "Q3+Q4 revenue是多少"}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py

# PPTX — 投影片查詢路線圖
echo '{"file_path": "data/test_slides.pptx", "query": "Q2 Roadmap 包含甚麼"}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py

# DOCX — Word 文件查詢成本
echo '{"file_path": "data/test_report.docx", "query": "Q2 cost"}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py

# XLSX — 試算表查詢產品價格
echo '{"file_path": "data/test_data.xlsx", "query": "widgetB price多少"}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py

# MD — Markdown 查詢功能說明
echo '{"file_path": "data/test_readme.md", "query": "featureB 是甚麼"}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py

# TXT — 純文字查詢日期
echo '{"file_path": "data/test_notes.txt", "query": "API 設計在幾月幾號"}' \
  | python3 .claude/skills/mcp-rag-pipeline/run.py

若在 Claude Code VSCode 中使用，可直接在聊天框輸入 skill 指令搭配檔案路徑與問題（不等於 shell 指令，Claude 會自動解析執行）：

/mcp-rag-pipeline /data/test_readme.md featureB 是甚麼
/mcp-rag-pipeline /data/test_report.docx Q2 cost
/mcp-rag-pipeline /data/test_data.xlsx widgetB price多少
/mcp-rag-pipeline /data/test_report.pdf Q3+Q4 revenue是多少
/mcp-rag-pipeline /data/test_notes.txt API 設計在幾月幾號
/mcp-rag-pipeline /data/test_slides.pptx Q2 Roadmap 包含甚麼

/doc-preprocessor-internal /data/test_report.docx

Skill 對照表

需求 Skill
離線解析，輸出 Markdown doc-preprocessor-internal
對文件提問（Q&A） mcp-rag-pipeline
取得 LLM-ready context mcp-rag-pipeline

詳細規格請參閱 docs/06_skill.md。

快速開始

1. 安裝

pip install -r requirements.txt

2. 下載 Embedding 模型（選用，啟用 Hybrid 搜尋）

跳過此步驟時，系統自動降級為純 BM25 搜尋；完成此步驟後，BM25 + Vector RRF fusion 全功能啟用。

# 安裝 dev 相依套件（torch / transformers / onnx，build-only）
pip install -e '.[dev]'

# 下載 BAAI/bge-small-zh-v1.5 並轉換為 ONNX，輸出至 models/bge-small-zh-v1.5/
python tools/setup_model.py

# 強制重新下載 / 轉換
python tools/setup_model.py --force

models/ 目錄已加入 .gitignore，模型檔案不會進版控。
Runtime 只需 onnxruntime，不需保留 torch / transformers。

3. 產生測試文件並建立知識庫

python generate_test_docs.py && python -m pipeline.ingest

4. 啟動 MCP Server

python mcp_server.py
# 加上 API key 保護：MCP_API_KEY=your-secret python mcp_server.py

查看日誌

# 即時追蹤日誌
tail -f logs/app.log

# 查看特定日期的輪換日誌
cat logs/app.log.2026-05-14

知識庫初始為空：共享文件需預先透過 ingestion pipeline 建立索引，或透過 upload_document 工具上傳私人文件。

MCP Tools

Tool 說明
search_knowledge_base 混合搜尋（BM25 + Vector RRF fusion），支援 top_k、doc_type_filter
search_docs search_knowledge_base 的別名
get_chunk 依 chunk_id 取得完整原文
list_documents 列出已索引的文件及統計
get_stats 知識庫整體統計
get_file_structure 瀏覽文件組織結構（PDF 按頁、PPTX/DOCX/XLSX 按節）
upload_document 上傳私人文件（Base64），支援 6 種格式，ChromaDB 持久化
search_my_document 搜尋已上傳的私人文件
remove_document 刪除已上傳的私人文件

文件

主題 路徑
架構與資料流 docs/01_architecture.md
Pipeline 模組 docs/02_pipeline_core.md
MCP Server docs/03_mcp_server.md
測試體系 docs/04_test_client.md
文件產生器 docs/05_generate_docs.md
Skills docs/06_skill.md
部署 docs/07_deployment.md
Embedding 引擎 docs/08_embeddings.md
端對端測試 docs/09_e2e_test.md
開發環境 docs/10_development.md

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

4 tags

Packages

 
 
 

Contributors

Languages