知识库只读查询器 (KB Reader)#

⚠️ 重要提示: 这是一个 严格只读 的查询系统，无法创建、上传、修改或删除任何数据。使用前必须确保已有管理员通过 kb-manager 初始化了系统环境。

专门用于查询和读取企业知识库内容的轻量级系统，不支持文档上传和管理功能。

使用方法#

对话式查询#

• 直接提问进行智能问答
• 支持语义搜索和关键词匹配
• 自动从知识库中检索相关内容

命令行使用#

bash

# 进入对话模式
python main.py chat

# 直接查询
python main.py query <查询内容>

# 列出文档（只读）
python main.py list

# 显示统计（只读）
python main.py stats

示例#

智能问答#

text

用户: 公司的休假政策是什么？
助手: 根据知识库文档，休假政策包括：
- 年假：每年15天带薪年假
- 病假：每年10天带薪病假
- 远程办公：每周可远程2天

文档查看#

text

用户: list documents
助手: 📚 知识库文档列表：
1. 公司政策.pdf (45 chunks)
2. 员工手册.docx (23 chunks)

🚀 快速开始#

1. 安装依赖#

bash

cd skills/kb-reader
pip install -r requirements.txt

2. 配置API密钥#

方式一：环境变量

powershell

# DashScope (阿里云千问) - 推荐
$env:DASHSCOPE_API_KEY='your-dashscope-key'

# 或者 OpenAI
$env:OPENAI_API_KEY='your-openai-key'

3. 确保知识库已初始化#

⚠️ 重要: kb-reader 是只读系统，无法创建或初始化知识库。使用前必须确保 kb-manager 已经初始化了系统环境。

bash

# 1. 检查系统目录是否存在
python main.py stats

# 2. 如果提示"系统数据目录不存在"，说明需要先用 kb-manager 初始化
# kb-reader 无法自行创建系统环境，必须由管理员使用 kb-manager 完成初始化

如果系统未初始化，请联系管理员或在有 kb-manager 的环境中运行：

bash

cd <kb-manager-directory>
python main.py setup

4. 测试查询#

bash

# 测试系统状态
python main.py stats

# 测试查询功能
python main.py query "测试查询"

📋 使用方法#

智能查询#

• 直接提问，系统会自动搜索相关文档
• 支持中文和英文查询
• 示例:
  • 公司的休假政策是什么？
  • 如何申请病假？
  • 远程办公的规定是什么？

文档浏览#

• python main.py list - 查看所有文档
• python main.py stats - 显示统计信息
• python main.py search <query> - 详细搜索文档内容

⚙️ 配置选项#

在 config.json 中设置:

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/

text

kb-data/
├── chroma_db/     # 向量数据库 (只读访问)
└── documents/     # 原始文档 (只读访问)

🔗 与kb-manager的关系#

• kb-manager: 负责创建和管理知识库，具有完整的读写权限

  • ✅ 创建系统目录 ( python main.py setup)
  • ✅ 上传和管理文档
  • ✅ 删除和修改数据
  • ✅ 初始化数据库

• kb-reader: 只能读取kb-manager创建的知识库， 严格只读权限

  • ❌ 无法创建系统目录
  • ❌ 无法上传文档
  • ❌ 无法修改或删除数据
  • ❌ 无法初始化数据库
  • ✅ 仅能查询和浏览现有数据

• 数据共享: 两个skills访问同一个系统目录，实现数据共享

• 权限分离: kb-reader无法修改或删除数据，确保数据安全

• 部署灵活: 可以部署在不同的agent上，实现分布式知识库访问

📋 使用前提#

1. 系统环境: 必须已经有管理员使用 kb-manager 初始化了系统环境
2. 只读权限: kb-reader 无法创建、修改或删除知识库数据
3. 数据存在: 知识库中必须已经有文档数据（由 kb-manager 上传）
4. API配置: 需要配置相同的嵌入模型API密钥
5. 依赖关系: kb-reader 完全依赖 kb-manager 创建的系统环境

🏗️ 技术特性#

• 严格只读: 代码层面限制，无任何写入或修改功能
• 高效检索: 基于向量相似度和关键词匹配
• 多种查询模式: 支持语义搜索、关键词搜索和混合搜索
• 轻量级: 最小化依赖，专注查询功能
• 兼容性: 可以读取kb-manager创建的知识库
• 安全设计: 无权限创建、修改或删除任何数据

🔧 故障排除#

知识库不存在#

bash

# 如果提示知识库不存在，kb-reader 无法自行解决此问题
# 必须联系管理员或在有 kb-manager 的环境中初始化

# 检查系统状态
python main.py stats

# 如果显示"系统数据目录不存在"，需要管理员运行：
# cd <kb-manager-directory>
# python main.py setup

注意: kb-reader 作为只读系统，无权限创建系统目录或初始化数据库。

无查询结果#

bash

# 检查知识库是否有数据
python main.py stats

# 如果没有数据，需要管理员使用 kb-manager 上传文档
# kb-reader 无法上传文档，只能查询已存在的数据

注意: kb-reader 无法上传文档，如需添加文档请联系管理员。

API密钥问题#

bash

# 检查环境变量 (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'

权限问题#

bash

# 如果遇到权限错误，检查系统目录权限
# 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#

text

同一台机器上的多个Agent
├── Agent-Admin (kb-manager)
├── Agent-User1 (kb-reader)
├── Agent-User2 (kb-reader)
└── 共享系统目录: C:/ProgramData/kb-data/

场景2: 分布式部署#

text

多台机器，共享网络存储
├── 机器A: Agent-Admin (kb-manager) → 网络存储
├── 机器B: Agent-User1 (kb-reader) → 网络存储
└── 机器C: Agent-User2 (kb-reader) → 网络存储

场景3: 容器化部署#

text

Docker容器间数据共享
├── Container-Admin: kb-manager + 数据卷
├── Container-User1: kb-reader + 数据卷
└── Container-User2: kb-reader + 数据卷

🔒 安全特性#

• 严格只读权限: 代码层面强制只读，任何写入操作都会抛出异常
• 无创建权限: 无法创建目录、数据库或集合
• 本地访问: 仅访问本地知识库文件
• API安全: 支持多种API提供商，密钥加密存储
• 数据隔离: 与kb-manager共享数据但权限完全隔离
• 故障安全: 如果系统环境不存在，会立即报错而不是尝试创建

📊 性能指标#

• 搜索延迟: <500ms (本地向量搜索)
• 内存占用: 最小化内存使用
• 并发支持: 支持多用户同时查询