使用说明

QA聊天机器人平台

概述

企业级问答平台使用LLM驱动的检索增强生成（RAG），具有代理功能和模型上下文协议（MCP）。

主要特点

🤖 代理RAG（检索增强生成）

智能多步推理：自动将复杂问题分解为重点子查询
查询计划：基于人工智能的分析，将问题分解为可回答的部分
交叉引用验证：验证多个来源的信息
推理轨迹：为代理人的思维过程提供透明的解释
自适应检索：根据查询复杂性动态调整搜索策略

🔍 矢量搜索和嵌入

可插拔矢量存储后端: VECTOR_STORE_BACKEND 在Azure Cosmos DB（默认）和OpenSearch k-NN搜索之间进行选择；两者都实现了相同的检索接口
Azure Cosmos数据库集成：具有1536个维度嵌入的原生向量索引
OpenSearch集成：k-NN（HNSW，余弦相似性）索引，首次使用时自动创建
语义相似性搜索：超越关键字匹配来理解意图
余弦距离函数：针对Azure OpenAI ada-002嵌入进行了优化
混合搜索：将矢量搜索与回退关键字搜索相结合
实时索引：文件上传后立即处理和搜索

🌐 MCP（模型上下文协议）集成

4标准化工具:
- search_documents：跨知识库的语义搜索
- retrieve_context：深度可配置上下文检索
- analyze_supply_chain：特定领域的供应链分析
- generate_insights：人工智能驱动的趋势、风险和机遇识别
JSON-RPC协议：LLM交互的标准通信格式
工具编排：工具的智能选择和链接

📊 供应链环境

供应链文件样本:
- 全球采购战略和供应商多样化
- 80多个国家的物流网络优化
- 供应商绩效管理和关键绩效指标
- 基于JIT和ABC分析的库存管理
特定域提示：为供应链运营量身定制
平台集成：数字采购平台参考
现实世界指标：实际绩效目标和基准

🏭 生产就绪架构

全面健康检查：多级监测（基本、详细、K8s探头）
结构化日志记录：带有相关ID的JSON格式日志
错误处理：具有优雅降级的全局异常处理程序
安全：API密钥认证、CORS配置、输入验证
审计日志：查询和文档访问的完整跟踪
速率限制就绪：已配置用于生产负载管理

🚀 附加功能

FastAPI后端：具有全面终结点的高性能异步API
流线型前端：用于文档上传和问答的交互式UI
多格式支持：PDF、DOCX、TXT和Markdown文档
对话历史：跟踪和检索以前的问答环节
来源引用：每个答案都包括对源文件的引用
性能指标：实时跟踪响应时间和准确性

建筑学

┌─────────────────┐
│   Streamlit UI  │
└────────┬────────┘
         │
    ┌────▼─────┐
    │  FastAPI │
    │  Backend │
    └────┬─────┘
         │
    ┌────▼──────────────────────┐
    │   Agentic RAG Pipeline    │
    │  ┌──────────────────────┐ │
    │  │  MCP Orchestrator    │ │
    │  └──────────────────────┘ │
    │  ┌──────────────────────┐ │
    │  │  Document Processor  │ │
    │  └──────────────────────┘ │
    │  ┌──────────────────────┐ │
    │  │  Vector Store        │ │
    │  └──────────────────────┘ │
    └────┬──────────────────────┘
         │
    ┌────▼────────────────┐
    │  Azure Cosmos DB    │
    │  (Vector Index)     │
    └─────────────────────┘
    ┌─────────────────────┐
    │  Azure OpenAI       │
    │  (GPT-4 + Embeddings)│
    └─────────────────────┘

包含内容

此存储库包含一个完整的、可用于生产的实现：

后端（FastAPI）

✅ 带有聊天和文档端点的RESTful API
✅ 带嵌入的Azure Cosmos DB矢量存储
✅ Azure OpenAI LLM和嵌入集成
✅ RAG管道实施
✅ 具有查询分解的代理RAG
✅ MCP（模型上下文协议）服务器
✅ 健康监测和记录
✅ 治理与合规特性

前端（Streamlit）

✅ 交互式聊天界面
✅ 文档上传功能
✅ 分析仪表板
✅ 源引用显示
✅ Agent推理可视化

数据和配置

✅ 4份综合样本文件
✅ 环境配置模板
✅ 初始化脚本
✅ 数据库设置自动化

DevOps与部署

✅ Docker和Docker组合文件
✅ 全面自述
✅ 快速入门指南
✅ 测试框架
✅ .gitignore和许可

先决条件

Python 3.10+
Azure订阅：
- Azure OpenAI 服务
- Azure Cosmos数据库（具有矢量搜索功能）
API访问凭据
Git

快速开始

1.克隆存储库

git clone <repository-url>
cd qa-chatbot

2.环境设置

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3.配置Azure凭据

# Copy environment template
cp .env.example .env  # Linux/Mac
copy .env.example .env  # Windows

# Edit .env with your Azure credentials
notepad .env  # Windows
nano .env     # Linux/Mac

所需配置：

# Azure OpenAI (Required)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-ada-002

# Azure Cosmos DB (Required)
COSMOS_DB_ENDPOINT=https://your-account.documents.azure.com:443/
COSMOS_DB_KEY=your-cosmos-key-here
COSMOS_DB_DATABASE_NAME=knowledge_base
COSMOS_DB_CONTAINER_NAME=documents

# API Configuration (Optional for demo)
API_ENDPOINT=https://api.example.com/api
API_KEY=your-scip-api-key

如何获取Azure凭据：

Azure OpenAI首选 Azure门户 → Azure OpenAI→ 密钥和端点
Cosmos数据库：Azure门户→ Cosmos数据库→ Keys → 主键和URI

4.测试Azure连接

# Verify your Azure credentials work
python scripts/test_connection.py

预期产量：

✅ Azure OpenAI: Embeddings working
✅ Azure OpenAI: LLM working
✅ Cosmos DB: Connected

5.初始化数据库

# Create Cosmos DB database and container with vector indexing
python scripts/init_database.py

这将创建：

数据库： knowledge_base
集装箱： documents 带矢量索引
1536维嵌入的向量嵌入策略

6.加载样本数据

# Ingest sample supply chain documents
python scripts/ingest_sample_data.py

取4份样本文件：

全球采购战略
物流网络优化
供应商绩效管理
库存管理实践

7.启动服务

终端1-FastAPI后端：

python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

2号航站楼-流线型前端：

streamlit run frontend/app.py --server.port 8501

终端3-MCP服务器（可选）：

python backend/mcp/server.py

8.访问申请

流线型UI: http://localhost:8501（主用户界面）
FastAPI文档: http://localhost:8000/docs（交互式API文档）
健康检查: http://localhost:8000/health（系统状态）
Redoc: http://localhost:8000/redoc（API替代文件）

9.试试看

问示例问题：

“全球采购战略是什么？”
“有多少个配送中心？”
“关键的供应商评估标准是什么？”
“解释库存优化方法”
“物流业的可持续发展举措是什么？”

10.上传到GitHub

cd qa-chatbot
git init
git add .
git commit -m "Initial commit: QA Chatbot Platform v1.0"
git branch -M main
git remote add origin https://github.com/your-username/qa-chatbot.git
git push -u origin main

重要：确保 .env 在...里 .gitignore 保护凭据！

项目结构

qa-chatbot/
├── backend/
│   ├── api/
│   │   ├── routes/
│   │   │   ├── chat.py           # Q&A endpoints
│   │   │   ├── documents.py      # Document management
│   │   │   └── health.py         # Health checks
│   │   └── dependencies.py       # Dependency injection
│   ├── core/
│   │   ├── config.py             # Configuration management
│   │   ├── logging.py            # Structured logging
│   │   └── security.py           # Authentication & authorization
│   ├── models/
│   │   ├── document.py           # Document models
│   │   ├── query.py              # Query models
│   │   └── response.py           # Response models
│   ├── services/
│   │   ├── embeddings.py         # Azure OpenAI embeddings
│   │   ├── llm.py                # LLM service
│   │   ├── vector_store.py       # Cosmos DB vector operations
│   │   ├── rag_pipeline.py       # RAG orchestration
│   │   └── agentic_rag.py        # Agentic RAG implementation
│   ├── mcp/
│   │   ├── server.py             # MCP server implementation
│   │   ├── tools.py              # MCP tools definition
│   │   └── protocol.py           # MCP protocol handlers
│   └── main.py                   # FastAPI application
├── frontend/
│   ├── app.py                    # Streamlit main app
│   ├── components/
│   │   ├── chat.py               # Chat interface
│   │   ├── upload.py             # Document upload
│   │   └── analytics.py          # Usage analytics
│   └── utils/
│       └── api_client.py         # Backend API client
├── data/
│   ├── sample/
│   │   ├── supply_chain_docs/    # Sample documents
│   │   └── procurement_data/     # Sample procurement data
│   └── schemas/
│       └── cosmos_schema.json    # Cosmos DB schema
├── scripts/
│   ├── init_database.py          # Database initialization
│   ├── ingest_sample_data.py     # Load sample data
│   └── test_connection.py        # Test Azure connections
├── tests/
│   ├── test_api.py               # API tests
│   ├── test_rag.py               # RAG pipeline tests
│   └── test_mcp.py               # MCP tests
├── .env.example                  # Environment template
├── .gitignore                    # Git ignore rules
├── requirements.txt              # Python dependencies
├── Dockerfile                    # Container definition
├── docker-compose.yml            # Multi-container setup
└── README.md                     # This file

使用示例

1.通过UI提问

导航到http://localhost:8501
在聊天界面输入您的问题
查看人工智能生成的带有源引用的回复

2.上传文件

点击侧边栏中的“上传文档”
选择PDF、DOCX或TXT文件
文档会自动处理和索引

3.API使用

import requests

# Ask a question
response = requests.post(
    "http://localhost:8000/api/v1/chat/ask",
    json={
        "question": "What are the latest supply chain trends?",
        "use_agentic": True,
        "max_sources": 5
    }
)

print(response.json())

治理与合规

数据分类

所有数据均被视为机密默认情况下。该平台实现了：

🔒 访问控制：基于角色的敏感文档访问
📝 审计日志：完成所有查询和访问的审计跟踪
🏷️ 数据标签：上传文档的自动分类
🛡️ 加密：静态和传输中加密的数据

合规性特征

GDPR合规性：数据保留政策和删除权
SOX合规性：财务数据查询的审计跟踪
数据治理：遵守数据治理政策

MCP（模型上下文协议）

该平台实现了用于标准化LLM交互的MCP：

# MCP tools available:
- search_documents: Semantic search across data
- retrieve_context: Get relevant context for queries
- analyze_supply_chain: Domain-specific analysis
- generate_insights: AI-powered insight generation

RAG代理能力

代理RAG系统可以：

计划：将复杂问题分解为子查询
研究：从多个来源收集信息
合成：智能地组合信息
验证：跨文档交叉检查事实
引用：为所有索赔提供来源参考

故障排除

常见问题

问题: ModuleNotFoundError: No module named 'azure'

pip install -r requirements.txt --upgrade

问题：Cosmos DB连接超时

检查Azure门户中的防火墙规则
验证COSMOS_DB_ENDPOINT和COSMOS_DB_ KEY
确保与Azure的网络连接

问题：超过OpenAI速率限制

实现请求限制
检查Azure门户中的配额
考虑升级Azure OpenAI层

日志

查看应用程序日志：

# Backend logs
tail -f logs/backend.log

# Streamlit logs
tail -f logs/streamlit.log

发展

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=backend --cov=frontend

# Run specific test
pytest tests/test_rag.py -v

代码质量

# Format code
black .

# Lint code
ruff check .

# Type checking
mypy backend/

部署

Docker部署

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Azure部署

看部署.md 有关Azure部署的详细说明。

性能优化

缓存：用于频繁查询的Redis缓存（可配置）
批处理：批量文件摄入
异步操作：API调用的非阻塞I/O
连接池：高效的数据库连接

监控

普罗米修斯指标：可在 /metrics
健康终点: /health, /health/db, /health/openai
结构化日志记录：JSON日志，便于解析

安全

API密钥验证
端点速率限制
输入验证和净化
CORS配置
通过环境变量进行秘密管理

贡献

创建要素分支： git checkout -b feature/new-feature
进行更改并提交： git commit -am 'Add new feature'
推送到分支： git push origin feature/new-feature
创建拉取请求

许可证

MIT 许可证

支持

对于问题或疑问：

在GitHub上创建问题
文档：https://api.example.com/docs

致谢

内置：

FastAPI和Streamlit
Azure OpenAI和Cosmos数据库
LangChain
模型上下文协议（MCP）

版本: 1.0.0
最后更新：2026年1月
维护者：开发团队