Enterprise Knowledge Agent

企业知识代理平台

   

一个采用现代AI Agent架构构建的生产就绪型企业知识管理系统，具有MCP协议支持、多LLM集成、混合RAG检索和全面可观察性。

目录

• 概述
• 建筑
• 特性
• 快速开始
• 安装
• 用法

- 命令行界面 - REST API - MCP服务器

• 配置
• 发展
• 部署
• 测试
• 文档
• 路线图
• 许可证
• 致谢

概述

企业知识代理是一个基于人工智能的系统，旨在帮助组织管理和查询其内部知识库。它将最先进的检索技术与智能代理功能相结合，提供准确的上下文响应和适当的源引用。

关键能力

• 智能文档检索：结合向量相似度和BM25关键字匹配的混合搜索
• 具有推理能力的AI代理：基于ReAct的代理，可以计划多步查询
• MCP协议支持：与Claude Desktop、Cursor和其他MCP兼容客户端集成
• 多LLM灵活性：在OpenAI、Anthropic Claude或当地Ollama模型之间切换
• 生产准备就绪：完成身份验证、速率限制、可观察性和部署配置

目标用例

• 企业知识库搜索
• 内部文件问答
• 人力资源政策咨询
• 技术文件协助
• 客户支持知识管理

建筑

┌────────────────────────────────────────────────────────────────────────┐
│                    Enterprise Knowledge Agent Platform                  │
├────────────────────────────────────────────────────────────────────────┤
│  Interface Layer                                                       │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐│
│  │ FastAPI REST    │  │  CLI Tool       │  │ MCP Server              ││
│  │ (Human/Systems) │  │  (Development)  │  │ (Claude, Cursor, etc.)  ││
│  └────────┬────────┘  └────────┬────────┘  └────────────┬────────────┘│
├───────────┴────────────────────┴────────────────────────┴─────────────┤
│  Agent Core Layer                                                      │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │                    Agent Orchestrator                           │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐    │   │
│  │  │Query Router  │→ │ReAct Engine  │→ │Response Synthesizer│    │   │
│  │  │(Intent)      │  │(Reasoning)   │  │(Citation + Format) │    │   │
│  │  └──────────────┘  └──────────────┘  └────────────────────┘    │   │
│  └────────────────────────────────────────────────────────────────┘   │
├───────────────────────────────────────────────────────────────────────┤
│  RAG Pipeline Layer                                                    │
│  ┌─────────────┐  ┌────────────────┐  ┌─────────────┐  ┌───────────┐  │
│  │  Ingestion  │  │ Hybrid Search  │  │  Reranker   │  │  Memory   │  │
│  │  Pipeline   │  │ Vector + BM25  │  │  (BGE)      │  │  Store    │  │
│  └─────────────┘  └────────────────┘  └─────────────┘  └───────────┘  │
├───────────────────────────────────────────────────────────────────────┤
│  Infrastructure Layer                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐  │
│  │  Qdrant     │  │  Redis      │  │  Postgres   │  │  S3/MinIO    │  │
│  │  (Vectors)  │  │  (Cache)    │  │  (Metadata) │  │  (Files)     │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  └──────────────┘  │
├───────────────────────────────────────────────────────────────────────┤
│  Observability Layer                                                   │
│  ┌─────────────────────────┐  ┌────────────────────────────────────┐  │
│  │  Arize Phoenix          │  │  Prometheus + Grafana              │  │
│  │  (LLM Tracing)          │  │  (System Metrics)                  │  │
│  └─────────────────────────┘  └────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────┘

设计原则

该系统遵循 六边形架构（端口和适配器） 图案：

• 核心层：RAG管道和代理逻辑，独立于接口
• 适配器：FastAPI REST、MCP服务器、CLI——都共享同一个核心
• 可扩展：易于添加新的LLM提供者、工具或接口

特性

快速开始

先决条件

• Python 3.11+
• Docker和Docker Compose
• OpenAI API密钥（或Anthropic/Ollama）

5分钟设置

# 1. Clone the repository
git clone https://github.com/yourusername/enterprise-knowledge-agent.git
cd enterprise-knowledge-agent

# 2. Install dependencies
poetry install

# 3. Set up environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 4. Start infrastructure (Qdrant, Redis, PostgreSQL)
docker compose -f deployment/docker-compose/docker-compose.yml up -d qdrant redis

# 5. Ingest sample documents
poetry run python -m src.cli ingest examples/sample_documents/

# 6. Start the API server
poetry run uvicorn src.api.main:app --reload

# 7. Try a query
curl -X POST http://localhost:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev-key" \
  -d '{"message": "What are the remote work guidelines?"}'

安装

使用诗歌（推荐）

# Install Poetry if you haven't
curl -sSL https://install.python-poetry.org | python3 -

# Install project dependencies
poetry install

# Activate virtual environment
poetry shell

使用pip

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or .venv\Scripts\activate  # Windows

# Install dependencies
pip install -e .

基础设施设置

# Start all services with Docker Compose
docker compose -f deployment/docker-compose/docker-compose.yml up -d

# Or start individual services
docker run -d -p 6333:6333 qdrant/qdrant          # Vector DB
docker run -d -p 6379:6379 redis:alpine            # Cache
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=password postgres:15  # Metadata

用法

命令行界面

# Ingest documents
poetry run python -m src.cli ingest ./documents/

# Interactive query
poetry run python -m src.cli query "What is our vacation policy?"

# Get system status
poetry run python -m src.cli status

REST API

启动服务器：

poetry run uvicorn src.api.main:app --reload --port 8000

API终点：

请求示例：

# Chat (non-streaming)
curl -X POST http://localhost:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "message": "How many vacation days do new employees get?",
    "top_k": 5
  }'

# Search documents
curl -X POST http://localhost:8000/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "query": "remote work",
    "top_k": 10
  }'

# Ingest document
curl -X POST http://localhost:8000/api/v1/ingest \
  -H "X-API-Key: your-api-key" \
  -F "file=@document.pdf"

交互式文档可在以下网址获得： http://localhost:8000/docs

MCP服务器

MCP服务器支持与Claude Desktop、Cursor和其他MCP兼容客户端的集成。

Claude桌面设置

添加到您的Claude桌面配置(~/.config/claude/mcp_servers.json):

{
  "knowledge-agent": {
    "command": "python",
    "args": ["-m", "src.mcp_server.server"],
    "cwd": "/path/to/enterprise-knowledge-agent",
    "env": {
      "OPENAI_API_KEY": "your-key"
    }
  }
}

可用的MCP工具

可用MCP资源

配置

环境变量

创建一个 .env 文件基于 .env.example:

# LLM Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OLLAMA_BASE_URL=http://localhost:11434

# Default LLM Settings
LLM_PROVIDER=openai          # openai, anthropic, ollama
LLM_MODEL=gpt-4              # Model name
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=2048

# Vector Database
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=knowledge_base

# Cache & Database
REDIS_URL=redis://localhost:6379
POSTGRES_URL=postgresql://user:pass@localhost:5432/knowledge_agent

# Observability
PHOENIX_ENDPOINT=http://localhost:6006
PROMETHEUS_ENABLED=true

# API Settings
APP_ENV=development
LOG_LEVEL=INFO

配置文件

发展

项目结构

enterprise-knowledge-agent/
├── src/
│   ├── agent/              # Agent orchestrator, router, ReAct engine
│   ├── api/                # FastAPI routes, middleware, schemas
│   ├── llm/                # LLM provider abstraction
│   ├── mcp_server/         # MCP protocol implementation
│   ├── observability/      # Tracing, metrics, evaluation
│   └── rag/                # RAG pipeline (ingestion, retrieval, generation)
├── configs/                # YAML configuration files
├── deployment/             # Docker, Kubernetes, scripts
├── docs/                   # Documentation
├── examples/               # Sample documents and notebooks
├── tests/                  # Unit, integration, e2e tests
└── scripts/                # Utility scripts

代码质量

# Format code
poetry run black src/ tests/
poetry run isort src/ tests/

# Lint
poetry run ruff check src/ tests/

# Type check
poetry run mypy src/

添加新的LLM提供程序

1. 在中创建提供程序类 src/llm/providers/:

from src.llm.base import BaseLLMProvider, LLMConfig

class MyProvider(BaseLLMProvider):
    @property
    def provider_name(self) -> str:
        return "my_provider"
    
    async def generate(self, messages, **kwargs) -> LLMResponse:
        # Implementation
        pass
    
    async def generate_stream(self, messages, **kwargs):
        # Implementation
        pass

1. 注册 src/llm/factory.py
2. 在中添加配置 configs/llm_configs/

添加新的MCP工具

1. 在中创建工具 src/agent/tools/:

from src.agent.tools import BaseTool, ToolParameter, ToolResult

class MyTool(BaseTool):
    @property
    def name(self) -> str:
        return "my_tool"
    
    @property
    def description(self) -> str:
        return "Description for LLM"
    
    @property
    def parameters(self) -> list[ToolParameter]:
        return [
            ToolParameter(name="param1", type=str, required=True)
        ]
    
    async def execute(self, **kwargs) -> ToolResult:
        # Implementation
        return ToolResult(success=True, data={...})

1. 注册 src/agent/tools/__init__.py
2. 在中添加MCP包装器 src/mcp_server/server.py

部署

Docker编写（开发/阶段）

# Start all services
docker compose -f deployment/docker-compose/docker-compose.yml up -d

# View logs
docker compose -f deployment/docker-compose/docker-compose.yml logs -f app

# Stop services
docker compose -f deployment/docker-compose/docker-compose.yml down

Kubernetes（生产）

# Apply manifests
kubectl apply -f deployment/kubernetes/

# Check status
kubectl get pods -l app=knowledge-agent

# View logs
kubectl logs -l app=knowledge-agent -f

环境特定配置

测试

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src --cov-report=html

# Run specific test categories
poetry run pytest tests/unit/           # Unit tests
poetry run pytest tests/integration/    # Integration tests
poetry run pytest tests/e2e/            # End-to-end tests

# Run MCP server tests
poetry run python scripts/test_mcp_server.py

测试类别

文档

路线图

完成

• \[x\] 第一阶段：基本RAG管道——文档摄取、分块、矢量搜索
• \[x\] 第2阶段：高级检索——混合搜索、重新排序、引用
• \[x\] 第三期：代理+MCP——查询路由器、ReAct引擎、MCP服务器
• \[x\] 阶段4：Multi-LLM+API-提供程序抽象、FastAPI、流
• \[x\] 阶段5：可观测性——凤凰追踪、普罗米修斯度量、拉加斯评估
• \[x\] 第6阶段：部署——Docker、Kubernetes、CI/CD

未来的增强功能

• \[\]多租户支持
• \[\]文档版本控制
• \[\]高级对话记忆
• \[\]自定义嵌入模型微调
• \[\]GraphRAG集成
• \[\]语音接口支持

性能指标

许可证

该项目根据MIT许可证获得许可——请参阅 许可证 文件以获取详细信息。

致谢

• FastMCP --MCP实施框架
• Llama索引 --RAG管道设计灵感
• LangChain --代理框架模式
• Qdrant --矢量数据库
• 干旱凤凰 --LLM可观测性
• 拉格 --RAG评估框架
• 句子变换器 --重新排列模型
• 排名bm25 --BM25实施

联系

有关此项目的问题或讨论，请在GitHub上打开问题。

______________________________________________________________________

Built with ❤️ as a portfolio project demonstrating enterprise AI Agent development

All 6 phases complete! 🎉