在实际 AI 编程项目中，直接调用大型语言模型生成代码虽然方便，但成本控制一直是个难题。尤其像 Codex 这类模型，生成质量高但 Token 消耗也大，如果每个代码细节都让它处理，项目预算很快就会见底。而像 DeepSeek 这类模型，在某些场景下性价比更高，但可能缺乏整体架构规划能力。有没有办法让它们协同工作，由强规划模型设计蓝图，再由高性价比模型执行具体编码任务呢？

这正是开源工具ai-code-orchestrator要解决的核心问题。它通过一个轻量级调度层，把代码生成任务拆解为“规划”和“执行”两个阶段，让不同 AI 模型各司其职。规划阶段使用 Codex 或类似的高阶模型分析需求、设计架构；执行阶段则调用 DeepSeek 或同类模型完成具体函数实现、代码补全等细节工作。这样既保证了代码结构的合理性，又显著降低了整体 Token 消耗。

本文将带你从零搭建一个基于该思路的 AI 代码编排工具。你会先理解模型调度的工作原理，然后配置多模型 API 密钥和环境，接着编写核心调度逻辑，最后通过实际代码生成任务验证工具效果。学完后，你可以在个人项目、团队原型开发或自动化代码生成场景中应用这种分层 AI 编程模式。

1. 理解 AI 代码编排的核心机制

1.1 为什么需要模型分工

单个 AI 模型在处理复杂编程任务时往往面临两难选择：通用大模型能力全面但成本高昂，专用小模型经济实惠但缺乏整体视野。如果把代码生成看作软件工程中的“设计-实现”流程，很自然就能想到用不同模型分别承担架构师和程序员角色。

规划模型（如 Codex）擅长理解自然语言需求，能够输出模块划分、接口设计、技术选型等高层决策。这些规划内容通常文本量不大，但需要较强的推理能力。执行模型（如 DeepSeek）则专注于将规划转化为具体代码，这类任务文本量大但逻辑相对直接，适合使用性价比更高的模型。

1.2 工具的工作流程

ai-code-orchestrator的基本工作流程分为四个阶段：

1. 需求解析：接收用户自然语言描述的需求，如“创建一个 Flask Web 应用，包含用户注册登录功能”。
2. 任务规划：调用规划模型分析需求，输出结构化任务清单，比如：创建项目结构、实现用户模型、编写认证路由、设计前端模板等。
3. 代码生成：根据任务清单，逐个调用执行模型生成具体代码文件。
4. 结果整合：将生成的代码文件组织到对应目录，并生成项目说明文档。

整个过程中，规划阶段只发生一次 API 调用，执行阶段根据任务数量进行多次调用，但每次调用都针对具体、有限的代码范围。

1.3 关键配置参数

工具的核心配置集中在模型选择和任务划分策略上：

规划模型的temperature通常设置较低，保证输出结构稳定；执行模型可以适当调高，让代码实现有一定多样性。

2. 环境准备与依赖配置

2.1 基础环境要求

工具基于 Python 3.8+ 开发，需要提前安装以下基础组件：

# 检查 Python 版本 python --version # Python 3.8.10 或更高 # 创建虚拟环境 python -m venv ai-code-env source ai-code-env/bin/activate # Linux/Mac # 或 ai-code-env\Scripts\activate # Windows # 升级 pip pip install --upgrade pip

2.2 安装核心依赖

创建requirements.txt文件，包含以下依赖：

openai>=1.0.0 requests>=2.25.0 python-dotenv>=0.19.0 pyyaml>=5.4.0 pathlib2>=2.3.0; python_version < '3.4'

安装依赖：

pip install -r requirements.txt

如果使用 DeepSeek API，还需要单独安装其 SDK：

pip install deepseek-api

2.3 配置 API 密钥

在项目根目录创建.env文件，配置各模型的 API 密钥：

# OpenAI API 配置（用于 Codex 等模型） OPENAI_API_KEY=sk-your-openai-key-here OPENAI_BASE_URL=https://api.openai.com/v1 # DeepSeek API 配置 DEEPSEEK_API_KEY=your-deepseek-key-here DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 # 其他模型 API 配置（按需添加） ANTHROPIC_API_KEY=your-claude-key-here

在代码中通过环境变量读取配置：

import os from dotenv import load_dotenv load_dotenv() OPENAI_API_KEY = os.getenv('OPENAI_API_KEY') DEEPSEEK_API_KEY = os.getenv('DEEPSEEK_API_KEY')

3. 实现核心调度逻辑

3.1 设计模型管理器类

首先创建模型管理器，统一处理不同模型的 API 调用：

import json import requests from openai import OpenAI class ModelManager: def __init__(self): self.openai_client = OpenAI(api_key=OPENAI_API_KEY) self.deepseek_headers = { 'Authorization': f'Bearer {DEEPSEEK_API_KEY}', 'Content-Type': 'application/json' } def call_planner(self, prompt, model="gpt-4"): """调用规划模型生成任务清单""" try: response = self.openai_client.chat.completions.create( model=model, messages=[ {"role": "system", "content": "你是一个资深软件架构师，请将用户需求拆解为具体的开发任务。"}, {"role": "user", "content": prompt} ], temperature=0.3, max_tokens=1000 ) return response.choices[0].message.content except Exception as e: print(f"规划模型调用失败: {e}") return None def call_executor(self, prompt, model="deepseek"): """调用执行模型生成代码""" if model == "deepseek": return self._call_deepseek(prompt) else: return self._call_openai(prompt, model) def _call_deepseek(self, prompt): """调用 DeepSeek API""" data = { "model": "deepseek-coder", "messages": [ {"role": "user", "content": prompt} ], "temperature": 0.7, "max_tokens": 2000 } try: response = requests.post( f"{DEEPSEEK_BASE_URL}/chat/completions", headers=self.deepseek_headers, json=data, timeout=30 ) response.raise_for_status() result = response.json() return result['choices'][0]['message']['content'] except requests.exceptions.RequestException as e: print(f"DeepSeek API 调用失败: {e}") return None def _call_openai(self, prompt, model): """调用 OpenAI 兼容 API""" try: response = self.openai_client.chat.completions.create( model=model, messages=[{"role": "user", "content": prompt}], temperature=0.7, max_tokens=2000 ) return response.choices[0].message.content except Exception as e: print(f"OpenAI API 调用失败: {e}") return None

3.2 实现任务解析器

规划模型输出的任务清单需要解析为结构化数据：

import re import yaml class TaskParser: def __init__(self): self.task_pattern = re.compile(r'(\d+)\.\s*(.*?):\s*(.*?)(?=\n\d+\.|\n*$)', re.DOTALL) def parse_plan(self, plan_text): """解析规划模型输出的任务清单""" tasks = [] matches = self.task_pattern.findall(plan_text) for match in matches: task_num, task_type, description = match task = { 'id': int(task_num.strip()), 'type': task_type.strip(), 'description': description.strip(), 'filename': self._generate_filename(task_type.strip(), description.strip()) } tasks.append(task) return tasks def _generate_filename(self, task_type, description): """根据任务类型生成文件名""" base_names = { '项目结构': 'project_structure', '模型定义': 'models', '路由实现': 'routes', '前端模板': 'templates', '配置文件': 'config', '工具函数': 'utils' } base_name = base_names.get(task_type, 'unknown') sanitized_desc = re.sub(r'[^a-zA-Z0-9]', '_', description.lower())[:20] return f"{base_name}_{sanitized_desc}.py"

3.3 创建代码编排器主类

整合模型管理和任务解析，实现完整的编排流程：

import os import time from pathlib import Path class CodeOrchestrator: def __init__(self, planner_model="gpt-4", executor_model="deepseek"): self.planner_model = planner_model self.executor_model = executor_model self.model_manager = ModelManager() self.task_parser = TaskParser() self.output_dir = "generated_code" # 创建输出目录 Path(self.output_dir).mkdir(exist_ok=True) def generate_project(self, requirement): """主方法：根据需求生成完整项目""" print("开始规划项目任务...") # 阶段1：任务规划 plan_prompt = f""" 请将以下开发需求拆解为具体的实现任务： {requirement} 请按以下格式输出： 1. 任务类型: 具体描述 2. 任务类型: 具体描述 ... """ plan_result = self.model_manager.call_planner(plan_prompt, self.planner_model) if not plan_result: print("规划阶段失败") return False print("规划结果：") print(plan_result) # 阶段2：任务解析 tasks = self.task_parser.parse_plan(plan_result) if not tasks: print("任务解析失败") return False print(f"解析出 {len(tasks)} 个任务") # 阶段3：代码生成 success_count = 0 for task in tasks: print(f"处理任务 {task['id']}: {task['type']}") code_prompt = f""" 请实现以下任务： {task['description']} 要求： - 生成完整的Python代码文件 - 包含必要的导入和注释 - 代码要符合PEP8规范 - 文件名：{task['filename']} """ code_content = self.model_manager.call_executor(code_prompt, self.executor_model) if code_content: self._save_code_file(task['filename'], code_content) success_count += 1 print(f"任务 {task['id']} 完成") # 避免API频率限制 time.sleep(1) # 阶段4：生成项目说明 self._generate_readme(requirement, tasks, success_count) print(f"项目生成完成，成功处理 {success_count}/{len(tasks)} 个任务") return True def _save_code_file(self, filename, content): """保存生成的代码文件""" filepath = Path(self.output_dir) / filename with open(filepath, 'w', encoding='utf-8') as f: f.write(content) def _generate_readme(self, requirement, tasks, success_count): """生成项目README文件""" readme_content = f""" # AI 生成项目 ## 原始需求 {requirement} ## 生成任务清单 {len(tasks)} 个任务，成功 {success_count} 个 ## 文件列表 """ for task in tasks: readme_content += f"- {task['filename']}: {task['description']}\n" readme_content += f""" ## 生成信息 - 规划模型: {self.planner_model} - 执行模型: {self.executor_model} - 生成时间: {time.strftime('%Y-%m-%d %H:%M:%S')} """ with open(Path(self.output_dir) / "README.md", 'w', encoding='utf-8') as f: f.write(readme_content)

4. 运行验证与效果分析

4.1 测试用例设计

创建一个测试脚本来验证工具功能：

def test_basic_functionality(): """基础功能测试""" orchestrator = CodeOrchestrator( planner_model="gpt-4", # 或 "codex" 如果可用 executor_model="deepseek" ) test_requirement = """ 创建一个简单的待办事项管理应用，包含以下功能： 1. 用户可以添加、查看、删除待办事项 2. 待办事项包含标题、描述、创建时间、完成状态 3. 数据使用JSON文件存储 4. 提供命令行界面操作 """ success = orchestrator.generate_project(test_requirement) if success: print("测试用例执行成功") # 检查生成的文件 output_files = list(Path("generated_code").glob("*.py")) print(f"生成文件数量: {len(output_files)}") for file in output_files: print(f"- {file.name}") else: print("测试用例执行失败") if __name__ == "__main__": test_basic_functionality()

4.2 运行结果分析

执行测试后，检查生成的项目结构：

python test_orchestrator.py

预期输出类似：

开始规划项目任务... 规划结果： 1. 项目结构: 创建基本的项目目录结构和入口文件 2. 模型定义: 定义待办事项的数据模型类 3. 存储管理: 实现JSON数据读写功能 4. 核心逻辑: 实现待办事项的增删改查操作 5. 命令行界面: 创建用户交互的命令行程序 解析出 5 个任务 处理任务 1: 项目结构 任务 1 完成 处理任务 2: 模型定义 任务 2 完成 ... 项目生成完成，成功处理 5/5 个任务 测试用例执行成功 生成文件数量: 5 - project_structure_todo_app.py - models_todo_item.py - utils_json_storage.py - routes_crud_operations.py - config_cli_interface.py

4.3 Token 消耗对比

通过实际调用统计 Token 使用情况：

这种分工策略在复杂项目中节省效果更明显，因为规划阶段的工作量相对固定，而执行阶段的任务数量会随项目复杂度线性增长。

5. 常见问题排查

5.1 API 调用失败处理

问题现象：模型调用返回错误或超时。

排查步骤：

1. 检查 API 密钥配置：

# 验证密钥格式 print(f"OpenAI Key: {OPENAI_API_KEY[:10]}...") print(f"DeepSeek Key: {DEEPSEEK_API_KEY[:10]}...")

2. 测试网络连接：

# 测试 API 端点可达性 curl -I https://api.openai.com/v1/models curl -I https://api.deepseek.com/v1/models

3. 检查配额和频率限制：

# 添加重试机制 import time from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) def call_api_with_retry(api_func, *args): return api_func(*args)

解决方案：

• 确认密钥有足够余额和权限
• 配置合理的超时时间和重试策略
• 使用指数退避算法避免频限

5.2 任务解析异常

问题现象：规划模型输出的任务清单无法正确解析。

可能原因：

• 规划模型输出格式不符合预期
• 任务描述包含特殊字符
• 正则表达式匹配失败

调试方法：

def debug_parser(plan_text): print("原始规划输出:") print(repr(plan_text)) # 显示原始格式 # 测试正则匹配 parser = TaskParser() matches = parser.task_pattern.findall(plan_text) print(f"匹配到 {len(matches)} 个任务") for i, match in enumerate(matches): print(f"匹配 {i+1}: {match}")

解决方案：

• 优化规划模型的提示词，明确输出格式要求
• 增强解析器的容错能力
• 添加格式验证和修复逻辑

5.3 生成代码质量不稳定

问题现象：不同任务生成的代码风格不一致或存在语法错误。

优化策略：

1. 细化执行模型的提示词：

improved_prompt = f""" 请实现以下任务： {task_description} 具体要求： 1. 使用Python 3.8+语法 2. 遵循PEP8代码规范 3. 添加必要的类型注解 4. 包含详细的文档字符串 5. 处理可能的异常情况 6. 编写相应的单元测试 生成完整的代码文件： """

2. 添加代码验证步骤：

import ast def validate_python_code(code_content): """验证Python代码语法""" try: ast.parse(code_content) return True except SyntaxError as e: print(f"代码语法错误: {e}") return False

6. 生产环境最佳实践

6.1 配置管理优化

生产环境建议使用配置文件而非环境变量：

# config.yaml models: planner: name: "gpt-4" api_key: "${OPENAI_API_KEY}" base_url: "https://api.openai.com/v1" parameters: temperature: 0.3 max_tokens: 1000 executor: name: "deepseek" api_key: "${DEEPSEEK_API_KEY}" base_url: "https://api.deepseek.com/v1" parameters: temperature: 0.7 max_tokens: 2000 orchestrator: max_tasks: 10 output_dir: "./projects" enable_validation: true

6.2 添加日志和监控

实现完整的日志记录和性能监控：

import logging from datetime import datetime class LoggingOrchestrator(CodeOrchestrator): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.setup_logging() def setup_logging(self): logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', handlers=[ logging.FileHandler(f'orchestrator_{datetime.now().strftime("%Y%m%d")}.log'), logging.StreamHandler() ] ) self.logger = logging.getLogger(__name__) def generate_project(self, requirement): self.logger.info(f"开始处理需求: {requirement[:100]}...") start_time = time.time() try: result = super().generate_project(requirement) duration = time.time() - start_time self.logger.info(f"项目生成完成，耗时: {duration:.2f}秒") return result except Exception as e: self.logger.error(f"项目生成失败: {e}") return False

6.3 安全考虑

在生产环境使用需要注意：

1. 代码安全扫描：对生成的代码进行安全审查

import subprocess def scan_generated_code(output_dir): """使用安全工具扫描生成代码""" try: result = subprocess.run( ['bandit', '-r', output_dir], capture_output=True, text=True ) if result.returncode != 0: print("安全扫描发现问题:") print(result.stdout) except FileNotFoundError: print("Bandit未安装，跳过安全扫描")

2. API 密钥管理：使用密钥管理服务而非明文存储
3. 访问控制：限制工具的使用权限和生成频率

6.4 性能优化建议

对于大规模使用场景：

1. 任务并行化：使用异步处理加速代码生成

import asyncio import aiohttp async def generate_tasks_parallel(tasks): """并行处理多个代码生成任务""" async with aiohttp.ClientSession() as session: tasks = [self.generate_single_task(session, task) for task in tasks] results = await asyncio.gather(*tasks, return_exceptions=True) return results

2. 结果缓存：对相似任务使用缓存避免重复生成
3. 增量生成：支持在已有项目基础上添加新功能

这种模型分工的策略不仅适用于代码生成，还可以扩展到文档编写、测试用例生成、代码审查等更多研发场景。关键是根据具体任务的特性，选择最适合的模型组合，在质量、成本和效率之间找到最佳平衡点。