AI-Robot

一个前后端分离的 AI 聊天机器人项目。它支持多轮对话、流式回答、模型切换、联网搜索，以及基于 Markdown 知识库和向量检索的智能客服能力。

功能特性

• 基于 SSE 的 AI 流式对话，支持 Markdown 和代码高亮
• 支持 deepseek-v3、deepseek-r1 模型切换
• 对话历史记录、分页加载、重命名和删除
• 可选 SearXNG 联网搜索
• Markdown 知识库文件的分片上传、秒传、管理和向量化
• 基于 PostgreSQL + pgvector 的 RAG 智能客服

技术栈

模块	技术
前端	Vue 3、Vite 6、Pinia、Vue Router、Ant Design Vue、Tailwind CSS
后端	Java 21、Spring Boot 3.4、Spring AI、MyBatis-Plus、WebFlux/SSE
数据库	PostgreSQL、pgvector、HikariCP、P6Spy
AI 服务	OpenAI 兼容接口；开发配置默认面向阿里云百炼 DashScope
联网搜索	SearXNG、OkHttp、Jsoup

系统结构

flowchart LR
    Browser["Vue 3 前端"] -->|REST / SSE| API["Spring Boot 后端"]
    API --> AI["OpenAI 兼容模型服务"]
    API --> DB["PostgreSQL / pgvector"]
    API --> Search["SearXNG（可选）"]
    API --> Files["Markdown 知识库文件"]

Loading

项目结构

AI-Robot/
├── xiaoha-ai-robot-springboot/  # Spring Boot 后端
│   ├── src/main/java/           # 业务代码
│   └── src/main/resources/      # 应用、日志、数据源配置及本地配置样例
├── xiaoha-ai-robot-vue3/        # Vue 3 前端
│   ├── src/api/                 # REST API 封装
│   ├── src/components/          # 通用组件
│   ├── src/views/               # 聊天和智能客服页面
│   └── src/stores/              # Pinia 状态管理
└── README.md

环境要求

• JDK 21
• Maven 3.9+
• Node.js 20+ 和 npm 10+
• PostgreSQL 14+，并安装 pgvector 扩展
• 可访问的 OpenAI 兼容模型服务
• SearXNG（可选，仅在启用联网搜索时需要）

请确认 mvn -version 显示的 Java 版本也是 21。只执行 java -version 还不够；如果 Maven 仍使用旧版 Java，请先修正 JAVA_HOME。

快速开始

1. 准备 PostgreSQL

创建数据库，并在目标数据库中启用 pgvector：

CREATE DATABASE robot;

-- 连接到 robot 数据库后执行
CREATE EXTENSION IF NOT EXISTS vector;

项目使用以下业务表：

• t_chat
• t_chat_message
• t_ai_customer_service_file_storage
• t_file_chunk_info
• t_vector_store

当前仓库尚未提供 Flyway/Liquibase 或独立 SQL 初始化脚本。首次启动前需要准备这些表；字段可参考后端的 domain/dos 实体类。建议后续补充版本化的数据库迁移脚本。

2. 创建本地配置

仓库只提交配置样例，真实的 application-dev.yml 只保存在本地并已加入 .gitignore：

cd xiaoha-ai-robot-springboot
Copy-Item src/main/resources/application-dev.yml.example src/main/resources/application-dev.yml

默认使用阿里云百炼的 DashScope OpenAI 兼容接口，需要配置百炼 API Key：

• 用途：调用 deepseek-v3、deepseek-r1 和 text-embedding-v4 等百炼模型。
• 获取位置：阿里云百炼控制台的“密钥管理/API Key”页面。
• 官方说明：如何获取 API Key。

推荐通过环境变量传入真实值，而不是直接写入本地 YAML。下面以 PowerShell 为例：

$env:BAILIAN_API_KEY = "your-bailian-api-key"
$env:AI_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode"
$env:DB_URL = "jdbc:p6spy:postgresql://localhost:5432/robot"
$env:DB_USERNAME = "postgres"
$env:DB_PASSWORD = "your-database-password"
$env:KNOWLEDGE_FILE_PATH = "D:\data\ai-robot\files"
$env:KNOWLEDGE_CHUNK_PATH = "D:\data\ai-robot\chunks"

需要联网搜索时，再配置 SearXNG：

$env:SEARXNG_URL = "http://localhost:8888/search"
$env:SEARXNG_COUNT = "10"

如果切换到其他 OpenAI 兼容模型服务，请同时修改 AI_BASE_URL、模型名称和对应服务商的 API Key。不要保留项目实际未使用的 DeepSeek、智谱或其他第三方 Key。部署时应通过密钥管理服务或 CI/CD Secret 注入敏感配置。

3. 启动后端

cd xiaoha-ai-robot-springboot
mvn spring-boot:run

后端默认监听 http://localhost:8080。

4. 启动前端

打开另一个终端：

cd xiaoha-ai-robot-vue3
npm ci
npm run dev

访问终端中 Vite 输出的地址，默认是 http://localhost:5173。开发服务器会将 /api 请求代理到 http://localhost:8080。

常用配置

环境变量	用途	默认/示例
BAILIAN_API_KEY	阿里云百炼 API Key	必填，从百炼控制台获取
AI_BASE_URL	OpenAI 兼容接口地址	DashScope 兼容模式地址
DB_URL	PostgreSQL 连接地址	jdbc:p6spy:postgresql://localhost:5432/robot
DB_USERNAME	数据库用户名	postgres
DB_PASSWORD	数据库密码	本地默认 postgres，生产环境必须修改
KNOWLEDGE_FILE_PATH	合并后的知识库文件目录	建议使用绝对路径
KNOWLEDGE_CHUNK_PATH	上传分片临时目录	建议使用绝对路径
SEARXNG_URL	SearXNG 搜索接口	http://localhost:8888/search
SEARXNG_COUNT	单次搜索结果数量	10

配置样例位于 xiaoha-ai-robot-springboot/src/main/resources/application-dev.yml.example。修改嵌入模型时，请同步调整 embedding 和 pgvector 的向量维度。

主要接口

方法	路径	说明
POST	/chat/new	新建对话
POST	/chat/completion	SSE 流式聊天
POST	/chat/list	查询历史对话
POST	/chat/message/list	查询历史消息
POST	/chat/summary/rename	重命名对话
POST	/chat/delete	删除对话
POST	/customer-service/completion	知识库智能客服对话
POST	/customer-service/file/check	检查文件是否可秒传
POST	/customer-service/file/upload-chunk	上传文件分片
POST	/customer-service/file/merge-chunk	合并文件分片并触发向量化
POST	/customer-service/file/list	查询知识库文件
POST	/customer-service/file/update	更新知识库文件信息
POST	/customer-service/file/delete	删除知识库文件

构建

后端：

cd xiaoha-ai-robot-springboot
mvn clean package

前端：

cd xiaoha-ai-robot-vue3
npm ci
npm run build

前端产物会生成在 xiaoha-ai-robot-vue3/dist/。

常见问题

• Maven 报 Java 版本错误：检查 mvn -version，并将 JAVA_HOME 指向 JDK 21。
• 提示数据表不存在：当前仓库不含数据库迁移脚本，需要先创建业务表和 pgvector 表。
• 向量维度不一致：确保嵌入模型维度与 spring.ai.vectorstore.pgvector.dimensions 相同。
• 联网搜索失败：确认 SearXNG 已启动、接口地址可访问，并返回 JSON 格式结果。
• 生产环境无法流式对话：前端聊天页目前直接访问本机 8080 端口；部署时需要将 SSE 地址改为实际后端地址或统一反向代理。

安全建议

• 所有 API Key、访问令牌和数据库密码都应通过环境变量或 Secret 管理服务注入。
• 本地 application-dev.yml 已加入 .gitignore；仓库只提交不含真实值的 .example 样例。
• 本地敏感配置文件应加入 .gitignore，提交前可使用 Gitleaks、TruffleHog 等工具扫描。
• 如果凭据曾经提交到 Git，即使在新提交中删除也仍存在于历史记录中；应立即吊销并轮换凭据，再清理 Git 历史。
• 生产环境应收紧 CORS、数据库权限和文件上传限制，不要沿用开发配置。

参与开发

欢迎通过 Issue 或 Pull Request 提交问题和改进。提交前请至少确认后端测试和前端构建能够通过，并再次检查变更中不包含任何敏感凭据。