# 元龙搜索算法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

### 软件依赖
```bash
# 核心依赖
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. **创建索引**：建议使用以下映射配置：
   ```json
   {
     "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. 查询分析与预处理
```python
# 输入：用户查询字符串
# 输出：处理后的查询参数
1. 检测查询中是否包含文件名模式
2. 估算查询的Token数量
3. 确定搜索策略（普通搜索/文件名导向搜索）
```

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

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

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

## 使用示例

### 基础安装与配置
```bash
# 从PyPi安装
pip install v6-search

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

### 快速开始
```python
from v6_search import IntelligentSearch

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

# 执行智能搜索
query = "2023年度财务报告分析"
max_tokens = 8000
results = search.intelligent_es_search_with_scoring(query, max_tokens)

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

### 高级配置示例
```python
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]}...")
```

### 文件名导向搜索
```python
# 当查询包含具体文件名时，算法会自动优化搜索策略
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估算与截断
```python
# 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}")
```

### 错误处理与回退
```python
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` 类

#### 构造函数
```python
__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. 使用实际模型进行验证
   ```

### 调试模式
```python
# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

search = IntelligentSearch(debug=True)
```

## 贡献指南

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

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

## 许可证

本项目采用MIT许可证。详见[LICENSE](LICENSE)文件。

## 支持与联系

- **GitHub仓库**：[https://github.com/bifu123/v6-search](https://github.com/yourusername/v6-search)
- **问题反馈**：[GitHub Issues](https://github.com/bifu123/v6-search/issues)
- **作者**：元龙居士

## 更新日志

### v1.0.0 (2024-01-22)
- 首次发布，包含完整的智能搜索算法
- 支持多维度相关性评分
- 实现智能内容截断和Token管理
- 提供完整的API文档和示例

---

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