【AI智能客服系统】02.项目部署与运行

# 项目环境准备

## 1. 环境要求

| 项目 | 推荐版本 |
|------|----------|
| Python | 3.10+ |
| MySQL | 5.7+ |
| Neo4j | 5.x（需安装 APOC 插件） |
| 开发 IDE | VS Code / PyCharm |

## 2. 创建 Python 环境

进入项目根目录：

```bash
cd D:\ycUpdate\guigu\llm_customer_service

创建并激活虚拟环境：

python -m venv .venv
.venv\Scripts\activate

安装项目依赖：

py -m pip install -r requirements-atguigu.txt

创建环境方式随便用哪种都行。

我一般用uv或者conda

3. 配置环境变量

复制或创建 ecs_demo/.env 文件，填入你的实际配置：

DASHSCOPE_API_KEY=你的百炼平台API_KEY
NEO4J_PASSWORD=你的neo4j密码
MYSQL_HOST=10.28.6.34
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=你的mysql密码
MYSQL_DATABASE=ecs
EMBEDDING_MODEL=./models/bge-base-zh-v1.5

注意 ：MYSQL_PASSWORD 必须改成你 MySQL 的真实 root 密码。

4. 准备 MySQL 数据

4.1 创建数据库

连接 MySQL 后执行：

drop database if exists ecs;
create database ecs;

4.2 导入表结构

mysql -h 10.28.6.34 -P 3306 -u root -p < "D:\ycUpdate\guigu\llm_customer_service\02_资料\业务数据准备\ecs.sql"

4.3 导入示例数据

mysql -h 10.28.6.34 -P 3306 -u root -p ecs < "D:\ycUpdate\guigu\llm_customer_service\02_资料\业务数据准备\ecs_sample_data.sql"

如果 ecs_sample_data.sql 不存在，可以先运行生成脚本：

cd "02_资料\业务数据准备"
py gen_sample_data.py

5. 准备 Neo4j 数据

5.1 安装 APOC 插件

若未安装 APOC 插件，后续步骤将无法执行并会报错，因此这是必须完成的安装项。

APOC（Awesome Procedures On Cypher）是 Neo4j 官方维护的核心插件库，提供了数百个用于数据集成、图形算法、数据转换和实用程序的存储过程与函数。在本项目中，安装 APOC 插件是必须的，主要原因如下：

1. 数据导入与转换 ：APOC 提供了强大的 apoc.load.json、apoc.import.csv 等过程，是高效导入外部数据（如本项目中的图数据）到 Neo4j 的关键工具。
2. 图算法与高级查询：它包含丰富的图算法（如路径查找、社区检测、中心性计算等），能显著增强基于知识图谱的检索（GraphRAG）能力。
3. 流程支持：本项目的某些自定义 Action 或检索逻辑可能依赖 APOC 提供的特定函数来完成复杂的数据操作。

因此，请务必完成以下安装与配置步骤，否则后续的图数据导入和项目运行可能会失败。

这个要安装和配置一下，

# 下载 APOC（版本需与 Neo4j 匹配，5.26.9 用 5.26.0）
Invoke-WebRequest -Uri "https://github.com/neo4j/apoc/releases/download/5.26.0/apoc-5.26.0-extended.jar" -OutFile "D:\devApp\neo4j-community-5.26.9\plugins\apoc-5.26.0-extended.jar"

# 编辑 D:\devApp\neo4j-community-5.26.9\conf\neo4j.conf，末尾添加:
dbms.security.procedures.unrestricted=apoc.*

# 重启 Neo4j
cd D:\devApp\neo4j-community-5.26.9\bin
.\neo4j.bat restart

5.2 导入图数据

cd D:\devApp\neo4j-community-5.26.9\bin

# 停止 Neo4j
.\neo4j.bat stop

# 导入 dump 文件
.\neo4j-admin.bat database load --from-path="D:\ycUpdate\guigu\llm_customer_service\02_资料\neo4j导入数据" --overwrite-destination=true neo4j

# 启动 Neo4j
.\neo4j.bat start

5.3 构建向量索引和全文索引

cd D:\ycUpdate\guigu\llm_customer_service\ecs_demo\addons
..\..\.venv\Scripts\python.exe create_indexing.py

6. 项目关键文件说明

ecs_demo/
├── config.yml              # 主配置（Pipeline + Policies）
├── endpoints.yml           # LLM、Neo4j、MySQL 端点配置
├── .env                    # 环境变量
├── data/flows/             # Flow 流程定义
│   ├── flow_order.yml
│   ├── flow_logistics.yml
│   └── flow_postsale.yml
├── domain/                 # 槽位、响应、Action 声明
│   ├── domain_order.yml
│   ├── domain_logistics.yml
│   └── domain_postsale.yml
├── actions/                # 自定义业务 Action
│   ├── action_order.py
│   ├── action_logistics.py
│   └── action_postsale.py
└── addons/                 # GraphRAG 检索器

7. 启动服务

必须在 ecs_demo 目录下启动 ，否则 .env 不会被正确加载：

# 方式一：CLI 命令
atguigu run -m ecs_demo

# 方式二：Python 模块
python -m atguigu_ai run -m ecs_demo

# 方式三：交互式调试
python -m atguigu_ai inspect -m ecs_demo

启动后访问：

• 对话界面：http://localhost:5005
• 交互测试：http://localhost:5005/inspect
• Neo4j Browser：http://localhost:7474

8. 验证

访问调试页面后，输入：

查询订单详情

如果配置正确，系统会进入 query_order_detail Flow，并展示当前用户的订单列表。

常见问题排查

1. ModuleNotFoundError: No module named 'dotenv'

原因 ：pyproject.toml 中 dependencies = [] 为空，pip install 未安装任何依赖。

解决 ：将 pyproject.toml 改为 dynamic = ["dependencies"]，让 pip 从 setup.py 读取依赖列表。

2. Neo4j 连接报错 apoc.meta.data not found

原因 ：Neo4jGraph(enhanced_schema=True) 需要 APOC 插件，本地 Neo4j 默认未安装。

解决：安装 APOC 插件（见上文"安装 Neo4j APOC 插件"章节）。

3. FileNotFoundError: Path ./models/bge-base-zh-v1.5 not found

原因 ：代码中使用相对路径 ./models/bge-base-zh-v1.5，工作目录不一致时找不到模型。

解决 ：在 .env 中配置绝对路径：

EMBEDDING_MODEL=D:\ycUpdate\guigu\llm_customer_service\ecs_demo\models\bge-base-zh-v1.5

4. No index with name xxx found / HybridRetriever 初始化失败

原因：Neo4j dump 仅导入图数据（节点和关系），未创建向量索引和全文索引。

解决 ：运行 create_indexing.py 构建索引（见上文"构建向量索引和全文索引"章节）。

5. WebSocket 超时无回复

原因：GraphRAG 内部连续调用 4-5 次 LLM（路由 → 检索 → Cypher 生成 → 验证 → 校正），总耗时 10-15 秒，前端 WebSocket 等不及断开。

解决：

1. 确保 Neo4j 数据已导入且索引已构建
2. 确保 DashScope API 网络通畅
3. 如仍有超时，可在前端增加 WebSocket 超时时间

6. 嵌入向量计算耗时较长

原因 ：初代 create_indexing.py 需要为所有节点（~1271 个）计算 768 维 embedding 向量，纯 CPU 运算。

注意：索引只需构建一次，后续重启服务无需重建。