知识库只读查询器 (KB Reader)
⚠️ 重要提示: 这是一个严格只读的查询系统，无法创建、上传、修改或删除任何数据。使用前必须确保已有管理员通过 kb-manager 初始化了系统环境。
专门用于查询和读取企业知识库内容的轻量级系统，不支持文档上传和管理功能。
使用方法
对话式查询
- 直接提问进行智能问答
- 支持语义搜索和关键词匹配
- 自动从知识库中检索相关内容
命令行使用
# 进入对话模式
python main.py chat
# 直接查询
python main.py query <查询内容>
# 列出文档（只读）
python main.py list
# 显示统计（只读）
python main.py stats
示例
智能问答
用户: 公司的休假政策是什么？
助手: 根据知识库文档，休假政策包括：
- 年假：每年15天带薪年假
- 病假：每年10天带薪病假
- 远程办公：每周可远程2天
文档查看
用户: list documents
助手: 📚 知识库文档列表：
1. 公司政策.pdf (45 chunks)
2. 员工手册.docx (23 chunks)
🚀 快速开始
1. 安装依赖
cd skills/kb-reader
pip install -r requirements.txt
2. 配置API密钥
方式一：环境变量
# DashScope (阿里云千问) - 推荐
$env:DASHSCOPE_API_KEY='your-dashscope-key'
# 或者 OpenAI
$env:OPENAI_API_KEY='your-openai-key'
3. 确保知识库已初始化
⚠️ 重要: kb-reader 是只读系统，无法创建或初始化知识库。使用前必须确保 kb-manager 已经初始化了系统环境。
# 1. 检查系统目录是否存在
python main.py stats
# 2. 如果提示"系统数据目录不存在"，说明需要先用 kb-manager 初始化
# kb-reader 无法自行创建系统环境，必须由管理员使用 kb-manager 完成初始化
如果系统未初始化，请联系管理员或在有 kb-manager 的环境中运行：
cd <kb-manager-directory>
python main.py setup
4. 测试查询
# 测试系统状态
python main.py stats
# 测试查询功能
python main.py query "测试查询"
📋 使用方法
智能查询
- 直接提问，系统会自动搜索相关文档
- 支持中文和英文查询
- 示例:
公司的休假政策是什么？如何申请病假？远程办公的规定是什么？
文档浏览
python main.py list- 查看所有文档python main.py stats- 显示统计信息python main.py search <query>- 详细搜索文档内容
⚙️ 配置选项
在 config.json 中设置:
{
"embeddingProvider": "dashscope",
"embeddingModel": "text-embedding-v3",
"embeddingBaseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"retrievalTopK": 5,
"milvusUri": "系统自动配置",
"collectionName": "enterprise_kb",
"documentsDir": "系统自动配置"
}
📁 系统数据目录
kb-reader 自动访问系统级知识库目录：
Windows: C:/ProgramData/kb-data/
Linux/Mac: /usr/local/share/kb-data/ 或 ~/.local/share/kb-data/
kb-data/
├── chroma_db/ # 向量数据库 (只读访问)
└── documents/ # 原始文档 (只读访问)
🔗 与kb-manager的关系
-
kb-manager: 负责创建和管理知识库，具有完整的读写权限
- ✅ 创建系统目录 (
python main.py setup) - ✅ 上传和管理文档
- ✅ 删除和修改数据
- ✅ 初始化数据库
- ✅ 创建系统目录 (
-
kb-reader: 只能读取kb-manager创建的知识库，严格只读权限
- ❌ 无法创建系统目录
- ❌ 无法上传文档
- ❌ 无法修改或删除数据
- ❌ 无法初始化数据库
- ✅ 仅能查询和浏览现有数据
-
数据共享: 两个skills访问同一个系统目录，实现数据共享
-
权限分离: kb-reader无法修改或删除数据，确保数据安全
-
部署灵活: 可以部署在不同的agent上，实现分布式知识库访问
📋 使用前提
- 系统环境: 必须已经有管理员使用 kb-manager 初始化了系统环境
- 只读权限: kb-reader 无法创建、修改或删除知识库数据
- 数据存在: 知识库中必须已经有文档数据（由 kb-manager 上传）
- API配置: 需要配置相同的嵌入模型API密钥
- 依赖关系: kb-reader 完全依赖 kb-manager 创建的系统环境
🏗️ 技术特性
- 严格只读: 代码层面限制，无任何写入或修改功能
- 高效检索: 基于向量相似度和关键词匹配
- 多种查询模式: 支持语义搜索、关键词搜索和混合搜索
- 轻量级: 最小化依赖，专注查询功能
- 兼容性: 可以读取kb-manager创建的知识库
- 安全设计: 无权限创建、修改或删除任何数据
🔧 故障排除
知识库不存在
# 如果提示知识库不存在，kb-reader 无法自行解决此问题
# 必须联系管理员或在有 kb-manager 的环境中初始化
# 检查系统状态
python main.py stats
# 如果显示"系统数据目录不存在"，需要管理员运行：
# cd <kb-manager-directory>
# python main.py setup
注意: kb-reader 作为只读系统，无权限创建系统目录或初始化数据库。
无查询结果
# 检查知识库是否有数据
python main.py stats
# 如果没有数据，需要管理员使用 kb-manager 上传文档
# kb-reader 无法上传文档，只能查询已存在的数据
注意: kb-reader 无法上传文档，如需添加文档请联系管理员。
API密钥问题
# 检查环境变量 (Windows)
echo $env:DASHSCOPE_API_KEY
# 检查环境变量 (Linux/Mac)
echo $DASHSCOPE_API_KEY
# 设置API密钥 (Windows)
$env:DASHSCOPE_API_KEY='your-api-key'
# 设置API密钥 (Linux/Mac)
export DASHSCOPE_API_KEY='your-api-key'
权限问题
# 如果遇到权限错误，检查系统目录权限
# Windows: C:/ProgramData/kb-data/
# Linux/Mac: /usr/local/share/kb-data/ 或 ~/.local/share/kb-data/
# 确保kb-manager有创建目录的权限
cd ../kb-manager
python main.py setup
🌐 部署场景
场景1: 单机多Agent
同一台机器上的多个Agent
├── Agent-Admin (kb-manager)
├── Agent-User1 (kb-reader)
├── Agent-User2 (kb-reader)
└── 共享系统目录: C:/ProgramData/kb-data/
场景2: 分布式部署
多台机器，共享网络存储
├── 机器A: Agent-Admin (kb-manager) → 网络存储
├── 机器B: Agent-User1 (kb-reader) → 网络存储
└── 机器C: Agent-User2 (kb-reader) → 网络存储
场景3: 容器化部署
Docker容器间数据共享
├── Container-Admin: kb-manager + 数据卷
├── Container-User1: kb-reader + 数据卷
└── Container-User2: kb-reader + 数据卷
🔒 安全特性
- 严格只读权限: 代码层面强制只读，任何写入操作都会抛出异常
- 无创建权限: 无法创建目录、数据库或集合
- 本地访问: 仅访问本地知识库文件
- API安全: 支持多种API提供商，密钥加密存储
- 数据隔离: 与kb-manager共享数据但权限完全隔离
- 故障安全: 如果系统环境不存在，会立即报错而不是尝试创建
📊 性能指标
- 搜索延迟: <500ms (本地向量搜索)
- 内存占用: 最小化内存使用
- 并发支持: 支持多用户同时查询