tw/MULTI_PROCESS.md

多进程异步并行架构

架构说明

当前架构（改造前）

单进程 + 单事件循环
┌─────────────────────┐
│ Python 进程          │
│ ┌─────────────────┐ │
│ │ asyncio Loop    │ │
│ │ 所有客户 + Agent  │ │
│ └─────────────────┘ │
└─────────────────────┘

问题：

• ❌ 单 CPU 核心
• ❌ 一个客户卡住影响全局
• ❌ 无法利用多核 CPU

---

新架构（改造后）

多进程 + 多事件循环
┌─────────┐  ┌─────────┐  ┌─────────┐
│进程 1    │  │进程 2    │  │进程 3    │
│Loop +   │  │Loop +   │  │Loop +   │
│客户 A,B │  │客户 C,D  │  │客户 E,F  │
└─────────┘  └─────────┘  └─────────┘
     ↓            ↓            ↓
  独立运行    独立运行    独立运行

优势：

• ✅ 真正的多核并行
• ✅ 故障隔离
• ✅ 负载均衡
• ✅ 可动态扩缩容

---

使用方法

方式 1：systemd 服务（推荐）

# 启动多进程模式
systemctl start ai-cs-multi

# 查看状态
systemctl status ai-cs-multi

# 查看日志
journalctl -u ai-cs-multi -f

# 停止服务
systemctl stop ai-cs-multi

方式 2：命令行启动

cd /root/ai_customer_service/ai_cs

# 使用默认进程数（CPU 核心数）
python3 scripts/multi_process_launcher.py

# 指定进程数
python3 scripts/multi_process_launcher.py --workers 4

---

配置说明

环境变量

变量	说明	默认值
AI_CS_WORKER_ID	工作进程 ID	0
AI_CS_SHARD_KEYS	本进程负责的客户 key	空

分片算法

客户按 acc_id:from_id 的 MD5 hash 值分配到不同进程：

shard_id = int(md5(f"{acc_id}:{from_id}").hexdigest(), 16) % num_workers

特点：

• 同一客户始终分配到同一进程
• 不同客户均匀分布
• 动态增减进程时自动重新平衡

---

监控

查看进程状态

# 查看所有工作进程
ps aux | grep ai-cs-worker

# 查看每个进程的 CPU 使用
top -p $(pgrep -d, -f ai-cs-worker)

日志查看

# 查看主进程日志
journalctl -u ai-cs-multi -f

# 查看特定工作进程日志
journalctl -u ai-cs-multi -f | grep "Worker 2"

---

性能对比

指标	单进程	多进程 (4 核)
并发客户数	~50	~200
CPU 使用率	25% (单核)	80% (4 核)
响应延迟	高	低
故障影响	全局	局部

---

注意事项

1. 进程数选择：

   • 默认 = CPU 核心数
   • 建议不超过 CPU 核心数 × 2

2. 内存占用：

   • 每个进程独立内存空间
   • 总内存 = 进程数 × 单进程内存

3. 日志管理：

   • 每个进程独立日志
   • 通过 worker_id 区分

4. 动态扩容：

   • 修改 --workers 参数
   • 重启服务自动重新分片

---

故障排查

Worker 进程退出

# 查看日志
journalctl -u ai-cs-multi -f | grep "Worker.*退出"

# 手动重启
systemctl restart ai-cs-multi

负载不均衡

# 查看每个进程处理的客户数
ps aux | grep ai-cs-worker | awk '{print $2}' | while read pid; do
  echo "PID $pid: $(ps -p $pid -o %cpu,%mem,cmd --no-headers)"
done

内存泄漏

# 监控内存使用
watch -n 1 'ps aux | grep ai-cs-worker | awk "{sum+=$6} END {print \"Total: \" sum/1024 \" MB\"}"'

---

使用 run.py 启动

单进程模式（默认）

cd /root/ai_customer_service/ai_cs

# 正常启动（含 AI Agent）
python3 run.py

# 不启用 AI Agent
python3 run.py --no-agent

多进程模式

cd /root/ai_customer_service/ai_cs

# 多进程模式（默认 CPU 核心数）
python3 run.py --multi

# 指定进程数
python3 run.py --multi --workers 4

systemd 服务

# 单进程模式
systemctl start ai-cs
systemctl status ai-cs
journalctl -u ai-cs -f

# 多进程模式
systemctl start ai-cs-multi
systemctl status ai-cs-multi
journalctl -u ai-cs-multi -f