AI 大模型分布式调度系统

C/S 架构智能调度系统：Server 端集成 AI 大模型（OpenAI API / Ollama），作为"中央大脑"接收自然语言指令；Client 端部署在各台电脑（Win/Mac/Linux），作为"手脚"被动等待调用。

项目架构

                    ┌───────────────────────────────────┐
                    │         Admin Web 控制台           │
                    │   http://server:8000（浏览器访问） │
                    └──────────────┬────────────────────┘
                                   │ WebSocket + REST
                                   ▼
┌─────────────────────────────────────────────────────────────┐
│                     Server（调度中心）                       │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ FastAPI 路由 │  │ AI Router     │  │ Device Manager    │  │
│  │ (main.py)   │  │ (ai_router)  │  │ (device_manager)  │  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬──────────┘  │
│         │                │                    │              │
│         └──────┬─────────┘                    │              │
│                ▼                              │              │
│       OpenAI / Ollama                        │              │
│       Function Calling                       │              │
└──────────────────────────────────────────────┼──────────────┘
                              WebSocket 长连接  │
                     ┌──────────┬───────────────┼───────┐
                     ▼          ▼               ▼       ▼
               ┌─────────┐ ┌─────────┐   ┌─────────┐ ┌─────────┐
               │ Client 1 │ │ Client 2 │   │ Client 3 │ │ Client N │
               │ (Win)    │ │ (Mac)    │   │ (Linux)  │ │ (...)    │
               └─────────┘ └─────────┘   └─────────┘ └─────────┘

• Server：FastAPI + WebSocket，集成大模型 Function Calling，将每台 Client 包装为 execute_command(device_id, shell_command) 工具
• Client：Python 脚本，主动发起 WebSocket 连接到 Server，被动等待指令执行并回传结果
• 通信：Client → Server WebSocket（长连接 + 心跳 + 指数退避重连），解决内网/无公网 IP 问题

---

环境要求

• Python 3.10+
• 可选硬件：NVIDIA GPU（本地 Ollama 推理推荐）

---

快速开始

1. 克隆项目 / 复制文件

# 假设项目位于 ~/Documents/agent
cd ~/Documents/agent

2. 安装依赖

pip install -r requirements.txt

如果使用 Ollama 本地推理，还需安装 Ollama 并拉取模型。

---

Server 配置

环境变量说明

变量	说明	默认值
OPENAI_API_KEY	API 密钥（Ollama 本地可填任意值）	ollama-local
OPENAI_BASE_URL	AI 模型 API 端点	http://localhost:11434/v1
MODEL_NAME	模型名称	qwen2.5:7b
SERVER_HOST	Server 监听地址	0.0.0.0
SERVER_PORT	Server 监听端口	8000

方案 A：使用 Ollama 本地模型（推荐无网/内网环境）

# 1. 安装 Ollama
brew install ollama          # macOS
# 或访问 https://ollama.com/download 下载安装包

# 2. 拉取模型
ollama pull qwen2.5:7b       # 推荐，轻量好用
# 或 ollama pull llama3.1:8b

# 3. 启动 Ollama 服务（通常自动运行）
ollama serve

# 4. 启动 Server
export OPENAI_BASE_URL="http://localhost:11434/v1"
export MODEL_NAME="qwen2.5:7b"
python server/main.py

方案 B：使用 OpenAI 官方 API

export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export MODEL_NAME="gpt-4o"
python server/main.py

方案 C：使用任何 OpenAI 兼容接口

# 例如 DeepSeek、智谱、通义千问等
export OPENAI_API_KEY="your_key"
export OPENAI_BASE_URL="https://api.deepseek.com/v1"
export MODEL_NAME="deepseek-chat"
python server/main.py

启动 Server

python server/main.py
# 或
uvicorn server.main:app --host 0.0.0.0 --port 8000

启动后访问 http://localhost:8000 进入 Admin 控制台。

---

Client 配置

启动 Client

python client/agent.py --server ws://server_ip:8000/ws/device --token your_auth_token

参数说明：

• --server：Server 的 WebSocket 地址（格式 ws://ip:端口/ws/device）
• --token：认证令牌，需与 Server 端一致

也可通过环境变量配置：

export AGENT_SERVER_URL="ws://192.168.1.100:8000/ws/device"
export AGENT_AUTH_TOKEN="my_secret_token"
python client/agent.py

安装为系统服务（开机自启）

# 安装
python client/installer.py install --server ws://192.168.1.100:8000/ws/device --token my_token

# 卸载
python client/installer.py uninstall

各平台实现方式：

• Windows：通过 NSSM 安装为 Windows 服务。如未找到 nssm.exe，请从 https://nssm.cc/download 下载
• macOS：通过 Launchd plist 安装为用户守护进程，写入 ~/Library/LaunchAgents/
• Linux：通过 systemd 用户级服务，写入 ~/.config/systemd/user/

---

使用流程

1. 在各台电脑上启动 Client（或安装为系统服务）
2. 打开浏览器访问 http://server_ip:8000
3. 左侧看到已注册的在线设备
4. 在输入框输入自然语言指令：
   • "查一下办公电脑的进程状态"
   • "帮我看看 Linux 服务器的磁盘使用情况"
   • "在所有 Windows 机器上检查 Windows 更新状态"
5. AI 会自动解析意图、选择目标设备、生成执行指令，并实时回显执行过程

---

安全建议

1. 修改默认 AUTH_TOKEN：生产环境中务必修改 .env 中的 AUTH_TOKEN 为强随机字符串
2. HTTPS/WSS：公网部署时建议使用 Nginx 反向代理 + Let's Encrypt 证书
3. 防火墙：仅信任内网 IP 范围访问 Server 8000 端口
4. 高危指令拦截：Server 端已内置黑名单（rm -rf、format、shutdown 等），命中后需在前端确认
5. 最小权限：Client 端运行账户应遵循最小权限原则，避免以 root/Administrator 运行

---

文件结构

agent/
├── server/
│   ├── __init__.py
│   ├── main.py              # FastAPI 主程序 + WebSocket 路由
│   ├── ai_router.py         # AI 接入 + Function Calling
│   ├── device_manager.py    # 设备注册与状态管理
│   └── templates/
│       └── index.html       # Admin Web 控制台
├── client/
│   ├── agent.py             # Client 代理主程序
│   └── installer.py         # 系统服务安装器
├── logs/                    # (运行时生成) 日志目录
├── requirements.txt
├── .env.example
├── start_server.sh
├── start_server.bat
└── README.md

---

常见问题 FAQ

Q: Client 连接不上 Server？ A: 检查防火墙是否放行 8000 端口，确认 Server 监听的是 0.0.0.0 而非 127.0.0.1。Client 端建议先用 ws:// 内网 IP 测试。

Q: Ollama 返回 "model not found"？ A: 先执行 ollama list 检查已下载的模型，然后用 ollama pull qwen2.5:7b 拉取。

Q: 高危指令确认后前端没有反应？ A: 确认 WebSocket 连接正常（页面刷新试试），浏览器控制台是否有报错。确认请求会通过 /api/confirm 回传给 Server。

Q: 如何添加更多 AI 后端？ A: 只要兼容 OpenAI API 格式（/v1/chat/completions）的服务都可以直接使用，修改 OPENAI_BASE_URL 即可。

Q: Client 端命令执行太慢？ A: 可在 ai_router.py 的 _wait_for_result 中调整超时时间（默认 90s），或在 agent.py 的 run_command 中调整（默认 60s）。

Q: 能同时调度多少台设备？ A: 理论上无硬性上限，但建议不超过 50 台以保证 WebSocket 连接池稳定性。大量设备可考虑使用 Redis Pub/Sub 做消息转发。