v6-search 1.0.1

Intelligent search algorithm V6 for Elasticsearch with multi-dimensional document retrieval

元龙搜索算法V6 - 智能文档检索库

项目的意义

元龙搜索算法V6旨在解决AI知识库中的核心矛盾："精准召回相关片段" 与 "在海量文档中快速搜索" 之间的平衡问题。

传统搜索方法面临以下挑战：

1. 精度与召回率的矛盾：高精度搜索可能错过相关文档，而高召回率搜索可能返回大量不相关结果
2. 中文文本处理的特殊性：中文分词、语义理解和Token估算的复杂性
3. 多维度相关性评估：需要综合考虑内容匹配、文件名相关性、时间因素等多个维度
4. 智能内容截断：如何在保持语义完整性的前提下截取最相关的片段

V6算法通过创新的多维度评分机制和智能内容选择策略，有效解决了这些挑战，实现了在大型文档库中的高效、精准检索。

项目特点

🧠 智能中文文本处理

• 自适应Token估算：针对中英文混合文本的智能Token计算（中文1.5字符=1Token，英文4字符=1Token）
• 语义边界截断：在句子边界处智能截断内容，保持语义完整性
• 中文分词优化：集成jieba分词库，支持自定义词典和停用词

📁 多维度文件名相关性评分

• Jaccard相似度：计算查询词与文件名的字符级相似度
• 时间相关性加权：基于文件修改时间的动态权重调整
• 文件类型智能加分：针对不同文件类型（表格、文档、PDF等）的差异化评分
• 精确匹配优先：完全匹配的文件名获得最高优先级

🔍 分层内容加载策略

• 优先级驱动的内容提取：根据相关性评分智能选择加载顺序
• Token预算管理：在指定Token限制内最大化信息价值
• 结构化内容保留：保持文档的原始结构和格式信息

🎯 文件名导向搜索

• 智能模式识别：自动检测查询中的文件名模式
• 针对性搜索优化：针对文件名搜索优化查询策略
• 多级回退机制：主搜索失败时的智能回退策略

⚡ 性能与可靠性

• 异步请求处理：支持并发Elasticsearch查询
• 错误恢复机制：网络异常时的自动重试和回退
• 配置灵活性：支持环境变量和参数化配置

项目依赖的前提

系统要求

• Python版本：>= 3.7
• Elasticsearch：7.8.0 (pip包、程序安装包版本也要相同)
• 操作系统：Windows/Linux/macOS

软件依赖

# 核心依赖
jieba>=0.42.1      # 中文分词库
requests>=2.28.0   # HTTP请求库

# 开发依赖（可选）
pytest>=7.0.0      # 测试框架
black>=23.0.0      # 代码格式化
mypy>=1.0.0        # 类型检查

Elasticsearch配置

1. 安装Elasticsearch：确保Elasticsearch服务正常运行
2. 创建索引：建议使用以下映射配置：

   {
     "mappings": {
       "properties": {
         "filename": {"type": "text", "analyzer": "ik_max_word"},
         "content": {"type": "text", "analyzer": "ik_max_word"},
         "filepath": {"type": "keyword"},
         "last_modified": {"type": "date"},
         "file_type": {"type": "keyword"}
       }
     }
   }
   

3. 数据导入：将文档内容索引到Elasticsearch中

算法的实现过程

1. 查询分析与预处理

# 输入：用户查询字符串
# 输出：处理后的查询参数
1. 检测查询中是否包含文件名模式
2. 估算查询的Token数量
3. 确定搜索策略（普通搜索/文件名导向搜索）

2. 多维度搜索执行

# 主要搜索阶段
1. 执行Elasticsearch查询，获取初步结果
2. 对每个结果计算多维度评分：
   - 内容相关性得分（BM25/向量相似度）
   - 文件名匹配得分（Jaccard相似度）
   - 时间相关性得分（基于文件新鲜度）
   - 文件类型加分（表格、文档等类型权重）
3. 综合评分排序

3. 智能内容选择与截断

# 内容处理阶段
1. 按评分优先级加载文档内容
2. 应用Token预算管理：
   - 估算每个片段的Token消耗
   - 在预算内选择最相关的片段
3. 语义边界截断：
   - 在句子、段落或章节边界处截断
   - 保持上下文的连贯性

4. 结果格式化与返回

# 输出阶段
1. 格式化搜索结果：
   - 包含来源文件信息
   - 显示相关性评分
   - 提供内容片段预览
2. 添加元数据：
   - 搜索耗时统计
   - Token使用情况
   - 匹配文档数量

使用示例

基础安装与配置

# 从PyPi安装
pip install v6-search

# 或从源码安装
git clone https://github.com/bifu123/v6-search.git
cd v6-search
pip install -e .

快速开始

from v6_search import IntelligentSearch

# 初始化搜索客户端
search = IntelligentSearch(
    es_url="http://192.168.66.38:9200",  # Elasticsearch地址
    es_index="file_index"        # 索引名称
)

# 执行智能搜索
query = "双拥资料目录"
max_tokens = 8000
results = search.intelligent_es_search_with_scoring(query, max_tokens)

print("搜索结果：")
print(results)

高级配置示例

import os
from v6_search import IntelligentSearch

# 使用环境变量配置
os.environ['ES_URL'] = "http://192.168.1.100:9200"
os.environ['ES_INDEX'] = "file_index"

# 创建搜索实例
search = IntelligentSearch()

# 执行带参数的搜索
results = search.intelligent_es_search_with_scoring(
    query="产品需求文档 PRD",
    max_tokens=10000,
    use_filename_search=True,      # 启用文件名导向搜索
    min_relevance_score=0.3,       # 最小相关性阈值
    include_metadata=True          # 包含元数据
)

# 处理搜索结果
for result in results.split('\n\n'):
    print(f"结果片段：{result[:200]}...")

文件名导向搜索

# 当查询包含具体文件名时，算法会自动优化搜索策略
queries = [
    "Q3季度销售数据.xlsx",          # 精确文件名搜索
    "用户调研报告2024.pdf",         # 部分匹配文件名
    "关于系统架构设计的会议纪要",    # 普通内容搜索
]

for query in queries:
    print(f"\n搜索查询：{query}")
    results = search.intelligent_es_search_with_scoring(query, 5000)
    print(f"返回结果数量：{len(results.split('---'))}个片段")

Token估算与截断

# Token估算示例
text_samples = [
    "这是一段纯中文文本，包含约50个字符。",
    "This is English text with about 30 characters.",
    "混合文本Mixed text with 中文and English。"
]

for text in text_samples:
    tokens = search.estimate_tokens(text)
    print(f"文本：{text[:30]}...")
    print(f"估算Token数：{tokens}")

# 智能截断示例
long_content = """第一章 项目概述
1.1 项目背景
本项目旨在开发一个智能文档检索系统...

1.2 项目目标
提高文档检索的准确性和效率...

第二章 技术方案
2.1 系统架构
采用微服务架构设计..."""

truncated = search.smart_truncate(long_content, max_tokens=100)
print(f"\n截断后的内容：\n{truncated}")

错误处理与回退

try:
    # 尝试主搜索策略
    results = search.intelligent_es_search_with_scoring(
        query="重要文档",
        max_tokens=8000
    )
except Exception as e:
    print(f"搜索失败：{e}")
    
    # 使用回退策略
    results = search.fallback_search(
        query="重要文档",
        max_tokens=8000
    )
    print(f"使用回退策略获得结果")

API参考

IntelligentSearch 类

构造函数

__init__(es_url=None, es_index=None)

• es_url: Elasticsearch服务地址，默认为环境变量ES_URL或"http://192.168.66.38:9200"
• es_index: Elasticsearch索引名称，默认为环境变量ES_INDEX或"file_index"

主要方法

intelligent_es_search_with_scoring(query, max_tokens=8000, use_filename_search=False, min_relevance_score=0.1)

执行智能搜索并返回格式化结果。

参数：

• query: 搜索查询字符串
• max_tokens: 返回内容的最大Token数（默认8000）
• use_filename_search: 是否启用文件名导向搜索（默认False）
• min_relevance_score: 最小相关性得分阈值（默认0.1）

返回值： 格式化的搜索结果字符串

estimate_tokens(text)

估算文本的Token数量。

smart_truncate(content, max_tokens)

在语义边界处智能截断文本。

filename_relevance_score(query, filename, last_modified=None)

计算文件名相关性得分。

filename_directed_search(query, max_tokens=8000)

执行文件名导向搜索。

性能优化建议

1. 索引优化

   • 为filename字段创建单独的关键字索引
   • 使用IK中文分词器优化中文搜索
   • 定期更新索引统计信息

2. 查询优化

   • 合理设置max_tokens参数，避免加载过多内容
   • 使用缓存机制存储频繁查询的结果
   • 批量处理多个搜索请求

3. 系统配置

   • 调整Elasticsearch的JVM内存设置
   • 使用连接池管理Elasticsearch连接
   • 监控搜索性能指标

故障排除

常见问题

1. 连接Elasticsearch失败

   解决方案：
   1. 检查Elasticsearch服务是否运行
   2. 验证网络连接和防火墙设置
   3. 确认URL和端口配置正确
   

2. 搜索结果不准确

   解决方案：
   1. 检查索引映射配置
   2. 优化分词器设置
   3. 调整相关性评分参数
   

3. Token估算偏差

   解决方案：
   1. 校准中英文Token比例参数
   2. 考虑特殊字符和标点的影响
   3. 使用实际模型进行验证
   

调试模式

# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

search = IntelligentSearch(debug=True)

贡献指南

我们欢迎各种形式的贡献！请参考以下步骤：

1. 报告问题：在GitHub Issues中描述遇到的问题
2. 功能建议：提出改进建议或新功能想法
3. 代码贡献：
   • Fork项目仓库
   • 创建功能分支
   • 提交Pull Request
4. 文档改进：帮助完善文档和示例

许可证

本项目采用MIT许可证。详见LICENSE文件。

支持与联系

• GitHub仓库：https://github.com/bifu123/v6-search
• 问题反馈：GitHub Issues
• 作者：元龙居士

更新日志

v1.0.0 (2024-01-22)

• 首次发布，包含完整的智能搜索算法
• 支持多维度相关性评分
• 实现智能内容截断和Token管理
• 提供完整的API文档和示例

---

元龙搜索算法V6 - 让文档检索更智能、更精准！