name: "doc-search" description: "处理文档向量化、存储和语义检索。支持 Word、Markdown、PDF、TXT 等格式。v3.0 新增查询缓存（速度提升 70x）、混合检索（BM25+ 向量）。Invoke when user needs to vectorize documents, search for similar content, or perform semantic queries on document collections." version: "v3.0.0"

文档向量检索技能

功能概述

提供完整的文档向量化和语义检索功能，能够： - 读取多种文档格式（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": "元数据"
    },
    ...
]

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

持久化存储

来源于7w4.net。

数据存储： - 向量数据：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 质量较好，功能丰富实用。它能处理多种文档格式、支持语义搜索和关键词检索，数据可以永久保存。文档说明详细清晰，容易上手。不过在中文分词和某些细节处理上还有优化空间，整体而言是一个可用性较高的文档检索工具，适合需要处理大量文档并需要进行智能搜索的场景。