knowledge-core-engine 0.1.6

Next-generation knowledge base engine with advanced RAG capabilities

KnowledgeCore Engine (K-Engine)

🚀 企业级RAG知识引擎 - 构建准确、可追溯、高性能的知识问答系统

快速开始 | 核心特性 | 安装指南 | 评测优化 | API文档

---

🌟 项目简介

KnowledgeCore Engine（简称K-Engine）是一个专为企业设计的高性能RAG（检索增强生成）知识引擎。它通过结合先进的文档处理、智能检索和精准生成技术，帮助企业构建可靠、可追溯的知识问答系统。

🎯 核心价值

• 准确性高：基于真实文档生成答案，大幅减少AI幻觉
• 可追溯性：每个答案都提供明确的引用来源
• 易于集成：提供简洁的Python API和REST API
• 成本优化：优先使用国产模型，显著降低使用成本
• 高度可扩展：模块化设计，支持自定义各个组件

快速开始

from knowledge_core_engine import KnowledgeEngine
import asyncio

async def main():
    # 创建引擎
    engine = KnowledgeEngine()
    
    # 添加文档
    await engine.add("data/source_docs/")
    
    # 提问
    answer = await engine.ask("什么是RAG？")
    print(answer)

asyncio.run(main())

就是这么简单！🎉

注意：确保您已经在 .env 文件中配置了API密钥，或通过环境变量设置。详见环境变量配置。

核心特性

📄 智能文档处理

• 支持多种格式：PDF、Word、Markdown、TXT等
• 使用LlamaParse进行高质量文档解析
• 智能分块策略，保持语义完整性
• 自动元数据增强，提升检索效果

🔍 高效检索系统

• 混合检索：结合语义搜索和关键词匹配
• 灵活的BM25支持：BM25S（轻量级）、Elasticsearch（企业级）
• 多种重排序选择：本地模型（BGE、Qwen）、API服务（DashScope、Cohere）
• 支持多种向量数据库：ChromaDB、Pinecone、Weaviate
• 智能查询扩展：提升检索召回率

💡 精准答案生成

• 集成多种LLM：DeepSeek、通义千问、OpenAI
• 自动引用标注，支持多种引用格式
• 流式生成支持，提升用户体验
• 链式思考（CoT）和自我批判机制

📊 评估与监控

• 内置评估框架，支持多维度指标
• 性能监控和使用统计
• A/B测试支持
• 完整的日志和追踪

安装指南

环境要求

• Python 3.11+
• 2GB+ RAM
• 10GB+ 磁盘空间（用于向量存储）

快速安装

# 克隆仓库
git clone https://github.com/Zephyrsailor/knowledge-core-engine.git
cd knowledge-core-engine

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装核心依赖
pip install -e .

# 可选：安装额外功能
pip install -e ".[reranker-hf]"    # 安装HuggingFace重排序模型支持
pip install -e ".[elasticsearch]"   # 安装Elasticsearch支持
pip install -e ".[dev]"            # 安装开发依赖

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的API密钥

环境变量配置

在.env文件中配置以下变量：

# 重要：所有环境变量使用 KCE_ 前缀，避免与其他项目冲突

# LLM配置（选择其一）
KCE_DEEPSEEK_API_KEY=your_deepseek_api_key
KCE_DASHSCOPE_API_KEY=your_dashscope_api_key  # 用于通义千问
KCE_OPENAI_API_KEY=your_openai_api_key  # 可选

# 文档解析
KCE_LLAMA_CLOUD_API_KEY=your_llama_parse_key  # 可选，提供1000次/天免费额度

# 向量数据库（ChromaDB默认无需配置）
# KCE_PINECONE_API_KEY=your_pinecone_key  # 如使用Pinecone
# KCE_WEAVIATE_URL=http://localhost:8080  # 如使用Weaviate

# 日志配置（可选）
# KCE_LOG_LEVEL=INFO  # 可选值: DEBUG, INFO, WARNING, ERROR

作为依赖库使用

如果你的项目需要将 KnowledgeCore Engine 作为依赖库使用：

# 从 PyPI 安装
pip install knowledge-core-engine

# 或从源码安装
pip install git+https://github.com/zephyrsailor/knowledge-core-engine.git

注意事项：

1. 所有环境变量都使用 KCE_ 前缀，避免与你的项目冲突
2. API keys 可以通过环境变量设置，也可以在代码中直接传入：

from knowledge_core_engine import KnowledgeEngine

# 方式1：使用环境变量（需要设置 KCE_ 前缀的环境变量）
engine = KnowledgeEngine()

# 方式2：直接传入 API keys（推荐）
engine = KnowledgeEngine(
    llm_api_key="your_deepseek_key",
    embedding_api_key="your_dashscope_key"
)

使用示例

import asyncio
from knowledge_core_engine import KnowledgeEngine

async def main():
    # 创建知识引擎
    engine = KnowledgeEngine()
    
    # 添加文档
    await engine.add("data/source_docs/")
    
    # 提问
    answer = await engine.ask("什么是RAG技术？")
    print(answer)

# 运行
asyncio.run(main())

更多使用示例

1. 获取详细信息

# 获取详细的答案信息
result = await engine.ask("什么是RAG？", return_details=True)

print(f"答案: {result['answer']}")
print(f"引用: {result['citations']}")
print(f"上下文: {result['contexts']}")

2. 搜索功能

# 搜索相关文档片段
results = await engine.search("检索增强", top_k=10)

for result in results:
    print(f"相关度: {result['score']:.3f}")
    print(f"内容: {result['content'][:100]}...")

高级功能

高级检索功能

K-Engine 提供了一系列高级检索功能，让您可以根据需求进行精细化配置：

检索策略

# 1. 纯向量检索（适合语义相似度匹配）
engine = KnowledgeEngine(
    retrieval_strategy="vector"
)

# 2. 纯关键词检索（适合精确匹配）
engine = KnowledgeEngine(
    retrieval_strategy="bm25"
)

# 3. 混合检索（默认，结合两者优势）
engine = KnowledgeEngine(
    retrieval_strategy="hybrid",
    vector_weight=0.7,  # 向量检索权重
    bm25_weight=0.3,    # BM25检索权重
    fusion_method="weighted"  # 可选: weighted, rrf
)

重排序

K-Engine 支持多种重排序方式，满足不同场景需求：

# 1. 使用本地 BGE 模型（推荐）
engine = KnowledgeEngine(
    enable_reranking=True,
    reranker_provider="huggingface",
    reranker_model="bge-reranker-v2-m3",
    use_fp16=True,  # 节省内存
    rerank_top_k=5
)

# 2. 使用本地 Qwen 模型（精度更高，适合36GB内存）
engine = KnowledgeEngine(
    enable_reranking=True,
    reranker_provider="huggingface",
    reranker_model="qwen3-reranker-8b",
    use_fp16=True,
    rerank_top_k=5
)

# 3. 使用 API 服务（无需本地资源）
engine = KnowledgeEngine(
    enable_reranking=True,
    reranker_provider="api",
    reranker_api_provider="dashscope",
    reranker_model="gte-rerank-v2",
    rerank_top_k=5
)

分块策略配置

# 层级分块（保留文档结构）
engine = KnowledgeEngine(
    enable_hierarchical_chunking=True,
    chunk_size=1024,
    chunk_overlap=128
)

# 语义分块（默认）
engine = KnowledgeEngine(
    enable_semantic_chunking=True,
    chunk_size=512,
    chunk_overlap=50
)

完整配置选项

engine = KnowledgeEngine(
    # 基础配置
    llm_provider="deepseek",             # 可选: deepseek, qwen, openai
    embedding_provider="dashscope",       # 可选: dashscope, openai
    persist_directory="./data/kb",        # 持久化目录
    log_level="INFO",                    # 日志级别: DEBUG, INFO, WARNING, ERROR
    
    # 分块配置
    enable_hierarchical_chunking=False,   # 层级分块
    enable_semantic_chunking=True,        # 语义分块
    chunk_size=512,                       # 分块大小
    chunk_overlap=50,                     # 分块重叠
    enable_metadata_enhancement=False,    # 元数据增强
    
    # 检索配置
    retrieval_strategy="hybrid",          # 可选: vector, bm25, hybrid
    retrieval_top_k=10,                   # 检索文档数量
    vector_weight=0.7,                    # 向量检索权重
    bm25_weight=0.3,                      # BM25权重
    
    # 查询扩展
    enable_query_expansion=False,         # 启用查询扩展
    query_expansion_method="llm",         # 扩展方法: llm
    query_expansion_count=3,              # 扩展数量
    
    # 重排序
    enable_reranking=False,               # 启用重排序
    reranker_provider="huggingface",      # 可选: huggingface, api
    reranker_model="bge-reranker-v2-m3",  # 重排序模型
    reranker_api_provider=None,           # API提供商: dashscope
    use_fp16=True,                        # 使用半精度（节省内存）
    rerank_top_k=5,                       # 重排后文档数
    
    # 其他配置
    include_citations=True,               # 是否包含引用
)

高级使用示例

# 高性能配置示例
engine = KnowledgeEngine(
    # 使用层级分块保留文档结构
    enable_hierarchical_chunking=True,
    enable_metadata_enhancement=True,
    
    # 混合检索
    retrieval_strategy="hybrid",
    
    # 启用查询扩展
    enable_query_expansion=True,
    
    # 使用重排序
    enable_reranking=True,
    reranker_model="bge-reranker-v2-m3",
    
    # 优化参数
    chunk_size=1024,
    retrieval_top_k=20,  # 初始检索更多文档
    rerank_top_k=5       # 重排后保留最相关的5个
)

# 添加文档
result = await engine.add("docs/")
print(f"处理了 {result['total_chunks']} 个文档块")

# 智能问答
answer = await engine.ask(
    "RAG技术的主要优势是什么？",
    return_details=True
)

print(f"答案: {answer['answer']}")
print(f"使用了 {len(answer['contexts'])} 个相关文档")
print(f"引用: {answer['citations']}")

REST API 服务

K-Engine提供了完整的REST API，方便集成到各种应用中。

启动API服务器

# 完整功能的API服务器（推荐）
python examples/api_server_simple.py

# 最小化API（仅健康检查）
uvicorn knowledge_core_engine.api.app:app --host 0.0.0.0 --port 8000

注意：examples/api_server.py 提供了完整的RAG功能API，包括文档上传、查询、流式响应等。 而 knowledge_core_engine.api.app 只是一个最小化的入口点。

API端点示例

上传文档

curl -X POST "http://localhost:8000/documents/upload" \
  -H "accept: application/json" \
  -F "file=@/path/to/document.pdf"

查询知识库

curl -X POST "http://localhost:8000/query" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "什么是RAG技术？",
    "top_k": 5,
    "include_citations": true
  }'

流式查询

const eventSource = new EventSource('http://localhost:8000/query/stream');
eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.content) {
        console.log(data.content);
    }
};

评测与优化

K-Engine 提供了完善的评测框架，帮助您评估和优化RAG系统的性能。

快速开始评测

# 运行评测（默认测试10个样本）
python scripts/run_evaluation.py

# 指定测试样本数
python scripts/run_evaluation.py --samples 5

# 查看帮助
python scripts/run_evaluation.py --help

评测流程说明

1. 准备知识库：从测试数据集中提取内容，创建评测用知识库
2. 生成答案：对每个测试问题运行完整的RAG流程
3. 计算指标：评估答案质量和系统性能
4. 生成报告：输出详细的评测结果

评测指标

• 成功率：成功生成答案的比例
• 关键词覆盖率：答案中包含标准答案关键词的比例（目标 > 60%）
• 平均答案长度：生成答案的平均字符数
• 评测耗时：完成评测所需时间

黄金测试集

项目包含两个精心设计的测试集：

• data/golden_set/rag_qa_dataset.json - RAG技术相关的10个测试用例
• data/golden_set/rag_test_set.json - 更多样化的测试场景
• 每个用例包含：问题、标准答案、理想检索内容、元数据

评测结果示例

{
  "summary": {
    "total_cases": 2,
    "successful_cases": 2,
    "success_rate": 1.0,
    "avg_keyword_coverage": 0.82,  // 82%的关键词覆盖率
    "avg_answer_length": 646.0
  },
  "metadata": {
    "config_profile": "default",
    "duration": 37.5  // 总耗时（秒）
  }
}

优化建议

1. 如果关键词覆盖率低（<60%）

   • 增加 retrieval_top_k 获取更多上下文
   • 启用混合检索策略 retrieval_strategy="hybrid"
   • 调整 BM25 权重以提高关键词匹配

2. 如果生成速度慢

   • 使用更快的模型（如 qwen-turbo）
   • 减少 max_tokens 限制
   • 关闭重排序或查询扩展功能

3. 如果答案质量不佳

   • 启用元数据增强 enable_metadata_enhancement=True
   • 使用更大的分块大小 chunk_size=1024
   • 启用层级分块保留文档结构

评测结果存储

• 位置：evaluation_results/ 目录
• 格式：evaluation_default_YYYYMMDD_HHMMSS.json
• 内容：包含完整的测试结果和性能指标

持续改进建议

1. 定期评测：每次重大更新后运行评测
2. 基准对比：保存基准结果用于对比改进
3. 逐步优化：先用少量样本测试，确认后再全量评测
4. 关注趋势：跟踪关键指标的变化趋势

系统架构

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   文档输入   │ ──▶ │  解析模块   │ ──▶ │  分块模块   │
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  生成模块   │ ◀── │  检索模块   │ ◀── │  向量存储   │
└─────────────┘     └─────────────┘     └─────────────┘
       │
       ▼
┌─────────────┐
│ 答案 + 引用 │
└─────────────┘

核心模块说明

1. 解析模块：使用LlamaParse将各种格式文档转换为统一的Markdown格式
2. 分块模块：智能分割文档，保持语义完整性
3. 向量存储：将文本转换为向量并高效存储
4. 检索模块：混合检索策略，快速找到相关内容
5. 生成模块：基于检索结果生成准确答案

性能优化建议

1. 文档处理优化

• 批量处理文档以提高效率
• 使用异步处理充分利用IO
• 合理设置分块大小（建议256-1024）

2. 检索优化

• 混合检索策略：结合向量检索和BM25关键词检索
• 重排序优化：BGE-reranker-v2-m3（平衡）、DashScope API（低成本）
• 合理设置top_k：初始检索15-20个，重排后保留3-5个

3. 生成优化

• 使用流式生成改善响应时间
• 选择合适的温度参数
• 启用缓存减少重复计算

4. 成本优化

• 优先使用国产模型（DeepSeek/Qwen）
• 合理设置max_tokens
• 使用本地向量数据库（ChromaDB）

测试

运行测试套件：

# 运行所有测试
pytest

# 运行特定模块测试
pytest tests/unit/core/generation/

# 查看测试覆盖率
pytest --cov=knowledge_core_engine --cov-report=html

贡献指南

我们欢迎所有形式的贡献！请查看CONTRIBUTING.md了解详情。

开发流程

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

代码规范

• 使用 ruff 进行代码格式化和检查
• 遵循 TDD（测试驱动开发）原则
• 所有公共API必须有文档字符串
• 提交信息遵循约定式提交

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

致谢

• LlamaIndex - 核心框架
• LlamaParse - 文档解析
• ChromaDB - 向量存储
• DeepSeek - LLM提供商
• DashScope - 嵌入和LLM服务

更多文档

• 配置指南 - 详细的配置系统说明
• 高级功能 - 深入了解高级特性
• 专业评测指南 - 完整的RAG系统评测方案
• 检索架构 - 深入理解检索系统设计

---