文件向量檢索技能

功能概述

提供完整的文件向量化和語義檢索功能，能夠：

• 讀取多種文件格式（Word、Markdown、PDF、TXT）
• 將文件分割成文本塊並生成向量嵌入
• 基於語義相似度進行智慧檢索
• 支援批次文件處理和查詢

使用場景

Invoke when:

• 使用者需要將文件轉換為向量進行儲存和檢索
• 使用者要求搜尋文件中與查詢語句相似的內容
• 使用者需要處理 Word、Markdown、PDF 等格式的文件
• 使用者需要進行語義搜尋而非關鍵詞匹配
• 使用者需要管理文件向量庫（新增、查詢、統計）

主要方法

1. vectorize_file(file_path, metadata)

將檔案向量化並新增到向量庫

引數：

• file_path: 檔案路徑（支援 .docx, .md, .pdf, .txt）
• metadata: 可選的後設資料字典

返回：

{
    "status": "success/error",
    "message": "操作訊息",
    "chunks_added": 切片數量,
    "source": "原始檔路徑"
}

2. search_vectors(query_text, top_k)

根據查詢文本檢索最相似的文件片段

引數：

• query_text: 查詢文本
• top_k: 返回的相似結果數量（預設 5）

返回：

[
    {
        "content": "文件內容",
        "similarity": 相似度 (0-1),
        "metadata": "後設資料"
    },
    ...
]
這個技能的最新版本可以在7w4.net小蔥技能站找到。

3. get_collection_stats()

獲取向量庫統計資訊

返回：

{
    "total_documents": 總文件數,
    "collection_name": 集合名稱
}

4. clear_collection()

清空向量庫所有資料

使用示例

基本文件向量化

from chromadb_document_vectorizer_simple import DocumentVectorizer

vector_service = DocumentVectorizer()

# 向量化文件
result = vector_service.vectorize_file("path/to/document.docx")
print(f"成功新增 {result['chunks_added']} 個文本切片")

語義搜尋

# 查詢相似內容
results = vector_service.search_vectors("智慧家居監測系統功能", top_k=3)

for idx, item in enumerate(results, 1):
    print(f"[{idx}] 相似度：{item['similarity'] * 100:.2f}%")
    print(f"內容：{item['content'][:100]}...")

批次處理多個文件

files = [
    "doc1.docx",
    "doc2.md", 
    "doc3.pdf"
]

for file in files:
    result = vector_service.vectorize_file(file)
    if result["status"] == "success":
        print(f"✅ {file}: {result['chunks_added']} 個切片")

獲取統計資訊

stats = vector_service.get_collection_stats()
print(f"總文件數：{stats['total_documents']}")

技術細節

文本分割

• 按中文句號（。）分割句子
• 每個切片預設 200 字元（可配置）
• 自動處理句子邊界，保持語義完整性

向量生成（雙模式）

模式 1: MD5 雜湊模擬（預設）

• 使用 MD5 雜湊生成 384 維向量
• 每個字元的 ASCII 值歸一化到 0-1
• 保證相同文本生成相同向量
• 無需額外依賴

模式 2: Sentence Transformers（推薦）

• 使用 paraphrase-multilingual-MiniLM-L12-v2 模型
• 真實的語義向量表示
• 支援多語言（中文、英文等）
• 需要安裝 sentence-transformers

持久化儲存

資料儲存：

• 向量資料：chroma_data/documents_data.pkl
• 檔案索引：chroma_data/documents_index.json
• 自動儲存：每次新增/刪除檔案後自動儲存
• 自動載入：初始化時自動恢復資料

相似度計算

• 使用餘弦相似度（Cosine Similarity）
• 值域：0-1（1 表示完全相同）
• 支援最小相似度閾值過濾

檔案格式支援

v3.0 重大改進（最新）

✅ 效能大幅提升

🚀 新增功能

1. 查詢快取（LRU）

• 自動快取熱門查詢
• 重複查詢速度提升 70 倍
• 可配置快取大小（預設 1000 條）

2. 混合檢索（BM25+ 向量）

• 關鍵詞匹配 + 語義相似度
• 可調節權重（alpha 引數）
• 檢索結果更精準

v2.0 重大改進

✅ 已解決的侷限性

使用真實 Embedding

# 安裝依賴
pip install sentence-transformers

# 使用真實 Embedding 模型
vectorizer = DocumentVectorizer(
    persist_directory="./chroma_data",
    use_real_embedding=True  # 啟用真實 Embedding
)

優勢：

• 🎯 語義理解更準確
• 🔍 檢索質量更高
• 🌍 支援多語言（中文、英文等）

注意：需要額外安裝 sentence-transformers 庫

效能建議

• 大檔案建議分批處理
• 查詢前確保已向量化相關文件
• 對於大量文件，考慮增加 chunk_size 減少切片數量
• 相似度閾值可根據需求調整（預設返回 top_k 個）

這個 Skill 質量較好，功能豐富實用。它能處理多種文件格式、支援語義搜尋和關鍵詞檢索，資料可以永久儲存。文件說明詳細清晰，容易上手。不過在中文分詞和某些細節處理上還有最佳化空間，整體而言是一個可用性較高的文件檢索工具，適合需要處理大量文件並需要進行智慧搜尋的場景。