AI dev vertical slice

AI驱动的3D工作流编排器-垂直切片

学校项目：人工智能工程师课程\ 2025年11月

______________________________________________________________________

📋 项目概述

这个垂直切片展示了一个人工智能驱动的管道，可以将自然语言命令转换为Blender 3D操作。该系统使用GPT-4来理解用户意图，并将命令路由到3D建模应用程序。

建筑

User Input (Web UI / Terminal)
    ↓
FastAPI Backend (REST API)
    ↓
LangGraph Agent (GPT-4o - Single Node)
    ↓
Tool Router (Python if/else)
    ↓
Blender MCP Socket Client (port 9876)
    ↓
Blender 3D Application

______________________________________________________________________

🎯 主要特点

• 自然语言处理：将纯英语命令转换为结构化命令
• 简单代理架构：用于命令解释的单节点LangGraph
• 刀具路径：将AI决策映射到特定的Blender操作
• 套接字通信：通过TCP套接字与Blender直接集成
• 双接口：用于测试的Web UI和终端客户端

______________________________________________________________________

🛠 技术栈

• 后端：FastAPI（Python）
• AI 代理：LangGraph+OpenAI GPT-4o
• 3D软件：搅拌机3.0+，带MCP插件
• 前端：普通HTML/CSS/JavaScript
• 沟通：REST API+TCP套接字

______________________________________________________________________

📁 项目结构

vertical_slice/
├── backend/
│   ├── main.py          # FastAPI server + endpoints
│   ├── agent.py         # LangGraph agent (single node)
│   ├── router.py        # Tool routing logic
│   └── mcp_client.py    # Blender socket client
├── ui/
│   └── index.html       # Web interface
├── test_client.py       # Terminal test client
├── requirements.txt     # Python dependencies
└── README.md           # This file

______________________________________________________________________

🚀 安装和设置

先决条件

1. Python 3.10+
2. 搅拌机3.0+
3. OpenAI API密钥
4. 搅拌机添加剂：

- 搅拌机MCP（用于插座通信） - QRemeshiffy（用于拓扑优化）

步骤1：安装依赖项

cd vertical_slice
pip install -r requirements.txt

步骤2：配置环境

创建 .env 项目根目录中的文件：

OPENAI_API_KEY=your-openai-api-key-here
BLENDER_HOST=localhost
BLENDER_PORT=9876

步骤3：安装Blender插件

A） 搅拌机MCP插件：

1. 下载： ../repos/blender-mcp/addon.py
2. 打开搅拌机→ Edit → 偏好设置→ 附加组件
3. 点击“安装…”→ 选择 addon.py
4. 启用“界面：搅拌机MCP”

B） QRemeshiffy插件：

1. 下载地址：https://github.com/ksami/QRemeshify/releases
2. 打开搅拌机→ Edit → 偏好设置→ 附加组件
3. 单击下拉箭头（右上角）→ “从磁盘安装…”
4. 选择下载的zip文件
5. 启用“qremeshiffy”

步骤4：启动Blender服务器

1. 在Blender中，按 N （打开侧边栏）
2. 查找“BlenderMCP”选项卡
3. 点击“连接到克劳德”按钮
4. ✅ 服务器在端口9876上运行

______________________________________________________________________

▶️ 运行应用程序

选项1:Web UI（推荐）

终端1-启动后端：

cd vertical_slice
python -m backend.main

浏览器： 打开： http://localhost:8000

键入以下命令：

• “创建多维数据集”
• “创建一个球体”

______________________________________________________________________

选项2：终端客户端

终端1-启动后端：

python -m backend.main

终端2-发送命令：

# Interactive mode
python test_client.py

# Single command
python test_client.py "create a cube"

______________________________________________________________________

🎮 支持的命令

______________________________________________________________________

🏗️ 运作原理

1.用户输入

用户在UI或终端中键入自然语言命令

2.FastAPI端点

POST /run
Body: {"text": "create a cube"}

3.LangGraph代理

单节点使用GPT-4o处理输入：

• 解析用户意图
• 提取参数
• 返回结构化JSON： {"tool": "create_cube", "args": {"size": 2.0}}

4.工具路由器

简单的Python函数：

if tool_name == "create_cube":
    return create_cube(size=args.get("size", 2.0))

5.MCP套接字客户端

向Blender发送JSON命令：

{
  "type": "execute_code",
  "params": {
    "code": "import bpy\nbpy.ops.mesh.primitive_cube_add(size=2.0)"
  }
}

6.搅拌机执行

Blender MCP插件接收命令，执行，返回状态

______________________________________________________________________

🧪 测试

测试1：基本立方体创建

Input: "create a cube"
Expected: Cube appears in Blender

测试2：球体创建

Input: "create a sphere"
Expected: Sphere appears in Blender

测试3：无效命令处理

Input: "what's the weather?"
Expected: Error message - "Please provide a Blender command"

______________________________________________________________________

🐛 故障排除

“连接被拒绝”

• ✅ 检查搅拌机是否正在运行
• ✅ 检查MCP插件是否处于活动状态
• ✅ 点击Blender侧栏中的“连接到克劳德”

“找不到OPENAI_API_KEY”

• ✅ 检查 .env 文件存在于项目根目录中
• ✅ 验证API密钥以开头 sk-
• ✅ 创建后重新启动服务器 .env 文件

“获取失败”（Web UI）

• ✅ 检查FastAPI服务器是否正在运行
• ✅ 通过访问UI http://localhost:8000 不 file://

虚拟环境问题

• ✅ 停用venv： deactivate
• ✅ 此项目使用Python系统

______________________________________________________________________

🔧 调试备忘单

端口8000已在使用中

# Find what's using port 8000
netstat -ano | findstr :8000

# Kill specific process (replace PID with number from above)
taskkill /F /PID 

# Kill all Python processes (nuclear option)
taskkill /F /IM python.exe

服务器无法启动

# 1. Check if port is free
netstat -ano | findstr :8000

# 2. Kill existing process
taskkill /F /PID 

# 3. Make sure you're in correct directory
cd C:\Users\TIGO\Desktop\vertical_slice

# 4. Start server
python -m backend.main

更改不起作用

# Always restart server after code changes!
# 1. Stop server: Ctrl+C
# 2. Start again: python -m backend.main

错误的虚拟环境

# Check if in venv (prompt shows (.venv))
# If yes, deactivate:
deactivate

# Then run normally:
python -m backend.main

快速重置（当一切都坏了）

# Kill all Python, restart fresh
taskkill /F /IM python.exe; cd C:\Users\TIGO\Desktop\vertical_slice; python -m backend.main

______________________________________________________________________

📊 设计决策

为什么选择单节点LangGraph？

• 简洁：更易于调试和理解
• 足够的：命令解析不需要复杂的推理
• 演出：延迟低于多节点图

为什么选择Socket连接？

• 直接：无中间件或协议开销
• 实时：Blender的即时反馈
• 现有的：利用现有的Blender MCP插件

为什么是最小UI？

• PoC焦点：展示概念，而不是生产抛光
• 无构建工具：单个HTML文件，易于运行
• 时效性：30分钟内建成

______________________________________________________________________

🔮 未来的增强功能

• 添加更多工具（灯光、相机、材质）
• 实现对话记忆
• 添加3D模型生成（网格集成）
• 支持复杂的多步骤工作流
• 错误恢复和重试逻辑
• 资产库浏览器

______________________________________________________________________

📝 主要学习内容

1. LangGraph架构：单节点代理足以完成简单的路由任务
2. 套接字通信：对于本地应用程序，直接集成比HTTP更快
3. 错误处理：清晰的错误消息对于调试至关重要
4. 双接口：终端+Web UI在开发过程中提供了灵活性

______________________________________________________________________

🎓 学术背景

课程：人工智能工程师\ 聚焦：实用的AI代理实现\ 范围：垂直切片展示核心管道\ 时间：一个晚上完成（约6小时）\ 代码行：~600（不包括UI组件）

______________________________________________________________________

📄 许可证

教育项目-免费使用和修改。

______________________________________________________________________

🙏 致谢

• 搅拌机MCP：Blender集成的开源插件
• 语言链/语言图：代理框架
• 开放人工智能：GPT-4o API
• 快速API：现代Python web框架

______________________________________________________________________

构建时注重清晰、简单和可证明的结果。