9196247578
- 新增 metadata_auto_inference_service 实现元数据自动推断 - 新增 kb_metadata_inference 提供知识库元数据推断工具 - 支持从文档内容自动提取元数据字段 - 集成缓存机制提升推断效率 |
||
|---|---|---|
| .claude/progress | ||
| .gitea/workflows | ||
| .vscode | ||
| ai-service | ||
| ai-service-admin | ||
| deploy | ||
| docs | ||
| java | ||
| scripts | ||
| spec | ||
| .env.example | ||
| .gitignore | ||
| AI中台对接文档.md | ||
| CLAUDE.md | ||
| README.md | ||
| agents.md | ||
| docker-compose.yaml | ||
| test-doc.txt | ||
README.md
AI Robot Core
AI中台业务的能力支撑，提供智能客服、RAG知识库检索、LLM对话等核心能力。
项目结构
ai-robot-core/
├── ai-service/ # Python 后端服务
│ ├── app/ # FastAPI 应用
│ ├── tests/ # 测试用例
│ ├── Dockerfile # 后端镜像
│ └── pyproject.toml # Python 依赖
├── ai-service-admin/ # Vue 前端管理界面
│ ├── src/ # Vue 源码
│ ├── Dockerfile # 前端镜像
│ ├── nginx.conf # Nginx 配置
│ └── package.json # Node 依赖
├── docker-compose.yaml # 容器编排
├── .env.example # 环境变量示例
└── README.md
功能特性
- 多租户支持: 通过 X-Tenant-Id 头实现租户隔离
- RAG 知识库: 基于 Qdrant 的向量检索增强生成
- LLM 集成: 支持 OpenAI、DeepSeek、Ollama 等多种 LLM 提供商
- SSE 流式输出: 支持 Server-Sent Events 实时响应
- 置信度评估: 自动评估回复质量，低置信度时建议转人工
快速开始
环境要求
- Docker 20.10+
- Docker Compose 2.0+
部署步骤
1. 克隆代码
git clone http://49.232.209.156:3005/MerCry/ai-robot-core.git
cd ai-robot-core
2. 配置环境变量
cp .env.example .env
编辑 .env 文件，配置 LLM API：
# OpenAI 配置
AI_SERVICE_LLM_PROVIDER=openai
AI_SERVICE_LLM_API_KEY=your-openai-api-key
AI_SERVICE_LLM_BASE_URL=https://api.openai.com/v1
AI_SERVICE_LLM_MODEL=gpt-4o-mini
# 或使用 DeepSeek
# AI_SERVICE_LLM_PROVIDER=deepseek
# AI_SERVICE_LLM_API_KEY=your-deepseek-api-key
# AI_SERVICE_LLM_MODEL=deepseek-chat
3. 启动服务
# Docker Compose V2 (推荐，Docker 内置)
docker compose up -d --build
# 或 Docker Compose V1 (旧版，需要单独安装)
docker-compose up -d --build
4. 拉取嵌入模型
服务启动后，需要在 Ollama 容器中拉取嵌入模型。推荐使用 nomic-embed-text-v2-moe，对中文支持更好：
# 进入 Ollama 容器拉取模型
docker exec -it ai-ollama ollama pull toshk0/nomic-embed-text-v2-moe:Q6_K
可选模型：
| 模型 | 维度 | 说明 |
|---|---|---|
toshk0/nomic-embed-text-v2-moe:Q6_K |
768 | 推荐，中文支持好，支持任务前缀 |
nomic-embed-text:v1.5 |
768 | 原版，支持任务前缀和 Matryoshka |
bge-large-zh |
1024 | 中文专用，效果最好 |
5. 配置嵌入模型
访问前端管理界面，进入 嵌入模型配置 页面：
- 选择提供者：Nomic Embed (优化版)
- 配置参数：
- API 地址：
http://ollama:11434（Docker 环境）或http://localhost:11434（本地开发） - 模型名称：
toshk0/nomic-embed-text-v2-moe:Q6_K - 向量维度：
768 - Matryoshka 截断：
true
- API 地址：
- 点击 保存配置
注意:
- 使用 Nomic Embed (优化版) provider 可启用完整的 RAG 优化功能：任务前缀、Matryoshka 多向量、两阶段检索。
- 嵌入模型配置会持久化保存到
ai-service/config/embedding_config.json，服务重启后自动加载。- 重要: 切换嵌入模型后，需要删除现有知识库并重新上传文档，因为不同模型生成的向量不兼容。
6. 验证服务
# 检查服务状态
docker ps
# 查看后端日志，找到自动生成的 API Key
docker logs -f ai-service | grep "Default API Key"
重要: 后端首次启动时会自动生成一个默认 API Key，请从日志中复制该 Key，用于前端配置。
7. 配置前端 API Key
# 创建前端环境变量文件
cd ai-service-admin
cp .env.example .env
编辑 ai-service-admin/.env，将 VITE_APP_API_KEY 设置为后端日志中的 API Key：
VITE_APP_BASE_API=/api
VITE_APP_API_KEY=<从后端日志复制的API Key>
然后重新构建前端：
cd ..
docker compose up -d --build ai-service-admin
7. 访问服务
| 服务 | 地址 | 说明 |
|---|---|---|
| 前端管理界面 | http://服务器IP:8181 | Vue 管理后台 |
| 后端 API | http://服务器IP:8182 | FastAPI 服务（Java渠道侧调用） |
| API 文档 | http://服务器IP:8182/docs | Swagger UI |
| Qdrant 控制台 | http://服务器IP:6333/dashboard | 向量数据库管理 |
| Ollama API | http://服务器IP:11434 | 嵌入模型服务 |
端口说明:
8181: 前端管理界面，内部代理后端 API8182: 后端 API，供 Java 渠道侧直接调用
服务架构
┌─────────────────────────────────────────────────────────┐
│ 用户访问 │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ ai-service-admin (端口8181) │
│ - Nginx 静态文件服务 │
│ - 反向代理 /api/* → ai-service:8080 │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ ai-service (端口8080) │
│ - FastAPI 后端服务 │
│ - RAG / LLM / 知识库管理 │
└─────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ PostgreSQL │ │ Qdrant │ │ Ollama │
│ (端口5432) │ │ (端口6333) │ │ (端口11434) │
│ - 会话存储 │ │ - 向量存储 │ │ - nomic-embed │
│ - 知识库元数据 │ │ - 文档索引 │ │ - 嵌入模型 │
└──────────────────┘ └──────────────────┘ └──────────────────┘
常用命令
# 启动所有服务
docker compose up -d
# 重新构建并启动
docker compose up -d --build
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f ai-service
docker compose logs -f ai-service-admin
# 重启服务
docker compose restart ai-service
# 停止所有服务
docker compose down
# 停止并删除数据卷（清空数据）
docker compose down -v
宿主机 Nginx 配置（可选）
如果需要通过宿主机 Nginx 统一管理入口（配置域名、SSL证书），可参考 deploy/nginx.conf.example：
# 复制配置文件
sudo cp deploy/nginx.conf.example /etc/nginx/conf.d/ai-service.conf
# 修改配置中的域名
sudo vim /etc/nginx/conf.d/ai-service.conf
# 测试配置
sudo nginx -t
# 重载 Nginx
sudo nginx -s reload
本地开发
后端开发
cd ai-service
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
# 安装依赖
pip install -e ".[dev]"
# 启动开发服务器
uvicorn app.main:app --reload --port 8000
前端开发
cd ai-service-admin
# 安装依赖
npm install
# 启动开发服务器
npm run dev
API 接口
核心接口
| 接口 | 方法 | 说明 |
|---|---|---|
/ai/chat |
POST | AI 对话接口 |
/admin/kb |
GET/POST | 知识库管理 |
/admin/rag/experiments/run |
POST | RAG 实验室 |
/admin/llm/config |
GET/PUT | LLM 配置 |
/admin/embedding/config |
GET/PUT | 嵌入模型配置 |
详细 API 文档请访问 http://服务器IP:8080/docs
环境变量说明
| 变量名 | 默认值 | 说明 |
|---|---|---|
AI_SERVICE_LLM_PROVIDER |
openai | LLM 提供商 |
AI_SERVICE_LLM_API_KEY |
- | API 密钥 |
AI_SERVICE_LLM_BASE_URL |
https://api.openai.com/v1 | API 地址 |
AI_SERVICE_LLM_MODEL |
gpt-4o-mini | 模型名称 |
AI_SERVICE_DATABASE_URL |
postgresql+asyncpg://... | 数据库连接 |
AI_SERVICE_QDRANT_URL |
http://qdrant:6333 | Qdrant 地址 |
AI_SERVICE_LOG_LEVEL |
INFO | 日志级别 |
License
MIT