MerCry
/
ai-robot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai中台业务的能力支撑
174 Commits 3 Branches 0 Tags 112 MiB
Python 73%
Vue 20.4%
TypeScript 3.9%
CSS 1.5%
Shell 1%
Other 0.2%
Go to file
MerCry a6276522c8 [AC-TEST] test: 新增单元测试和集成测试 
- 新增 test_image_parser 图片解析器测试
- 新增 test_llm_multi_usage_config LLM 多用途配置测试
- 新增 test_markdown_chunker Markdown 分块测试
- 新增 test_metadata_auto_inference 元数据推断测试
- 新增 test_mid_dialogue_integration 对话集成测试
- 新增 test_retrieval_strategy 检索策略测试
- 新增 test_retrieval_strategy_integration 检索策略集成测试
 		2026-03-11 19:10:05 +08:00
.claude/progress feat(v0.7.0): 验收通过 - Dashboard统计增强、流程测试、对话追踪 2026-02-28 12:52:50 +08:00
.gitea/workflows 初始化初始文档 2026-02-24 12:08:24 +08:00
.vscode feat: add timeout and retry configuration for LLM client [AC-AISVC-LLM] 2026-03-06 02:02:03 +08:00
ai-service [AC-TEST] test: 新增单元测试和集成测试 2026-03-11 19:10:05 +08:00
ai-service-admin [AC-LLM-MULTI] feat(llm): 实现 LLM 多用途配置功能 2026-03-11 18:56:01 +08:00
deploy feat: 调整端口映射，后端8182供Java渠道侧调用 [AC-AISVC-01] 2026-02-26 01:46:24 +08:00
docs [AC-LLM-MULTI] feat(llm): 实现 LLM 多用途配置功能 2026-03-11 18:56:01 +08:00
java docs: add ai-service provider openapi [AC-AISVC-01] 2026-02-24 12:43:57 +08:00
scripts 初始化初始文档 2026-02-24 12:08:24 +08:00
spec [AC-AISVC-RES-01~15] docs(spec): 新增检索策略路由规范文档 2026-03-10 21:05:53 +08:00
.env.example feat: 添加API Key认证系统和修复Qdrant搜索问题 [AC-AISVC-50] 2026-02-26 03:11:36 +08:00
.gitignore feat(v0.7.0): 验收通过 - Dashboard统计增强、流程测试、对话追踪 2026-02-28 12:52:50 +08:00
AI中台对接文档.md feat: implement output guardrail with forbidden word detection and behavior rules [AC-AISVC-78~AC-AISVC-85] 2026-02-27 16:40:02 +08:00
CLAUDE.md docs: add CLAUDE.md for project guidance 2026-03-05 20:36:41 +08:00
README.md fix: 适配qdrant-client 1.17.0 API变更，search方法改为query_points [AC-AISVC-50] 2026-02-26 19:07:04 +08:00
agents.md feat(v0.7.0): 验收通过 - Dashboard统计增强、流程测试、对话追踪 2026-02-28 12:52:50 +08:00
docker-compose.yaml chore: 修改前端端口映射为8183 [AC-AISVC-50] 2026-02-26 20:05:39 +08:00
test-doc.txt feat(AISVC-T8): LLM配置管理与RAG调试输出支持 [AC-AISVC-42, AC-AISVC-43, AC-AISVC-44, AC-AISVC-45, AC-AISVC-46, AC-AISVC-47, AC-AISVC-48, AC-AISVC-49, AC-AISVC-50] 2026-02-25 01:25:53 +08:00

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. 配置嵌入模型

访问前端管理界面，进入 嵌入模型配置 页面：

  1. 选择提供者：Nomic Embed (优化版)
  2. 配置参数：
    • API 地址：http://ollama:11434（Docker 环境）或 http://localhost:11434（本地开发）
    • 模型名称：toshk0/nomic-embed-text-v2-moe:Q6_K
    • 向量维度：768
    • Matryoshka 截断：true
  3. 点击 保存配置

注意:

  • 使用 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: 前端管理界面，内部代理后端 API
  • 8182: 后端 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