最近在探索AI Agent的落地场景时发现很多演示都停留在简单的问答或工具调用上缺乏动态、连续决策的复杂环境。这让我思考能否构建一个更“好玩”、更能体现智能体自主决策能力的竞技场受此启发我们团队尝试复现并深度解析了Hacker News上热议的“Agentic World Cup”项目——一个让大型语言模型LLM在1v1足球模拟环境中自主对抗的竞赛平台。本文将带你从零开始深入理解其架构并手把手教你搭建自己的“AI足球联赛”体验LLM在动态环境中的策略博弈。本文适合对AI Agent、多智能体系统、LLM应用开发感兴趣的开发者。无论你是想了解Agentic设计模式还是希望为你的LLM寻找一个有趣的评估沙盒都能在这里找到完整的代码、配置与实战经验。我们将覆盖从环境搭建、智能体设计、比赛运行到结果分析的完整闭环。1. 背景与核心概念为什么是“AI足球”在深入代码之前我们首先要厘清几个关键概念并理解这个项目背后的意义。1.1 什么是 Agentic AI“Agentic”一词源于“Agent”智能体它描述的是一种能够感知环境、自主设定目标、制定并执行计划以达成目标的AI系统。与传统的一次性问答不同Agentic AI强调持续性、目标导向性和工具使用能力。一个Agentic LLM不仅会回答问题还会在长期任务中分解步骤、使用外部工具如搜索、计算、执行代码并适应环境变化。1.2 从传统RAG到Agentic RAG的演进搜索热词中提到了“从传统RAG到Agentic RAG的进阶优化”。这揭示了当前的一个技术趋势传统RAG (Retrieval-Augmented Generation)主要用于增强LLM的知识通过检索相关文档来生成更准确的答案。它是一个被动的、响应式的系统。Agentic RAG将RAG能力嵌入到一个主动的智能体中。智能体可以主动决定何时进行检索、检索什么、如何利用检索到的信息来推进一个多步骤的任务。这体现了“Agentic”的自主决策特性。我们的足球Agent就是一个简化版的Agentic系统它需要根据球场状态环境主动决定行动如传球、射门以达成进球的目标。1.3 项目核心价值一个理想的智能体测试床为什么选择足球作为测试场景动态环境球场状态瞬息万变要求智能体进行实时感知和决策。长期规划从后场组织到前场射门需要多步连贯的策略而非单次反应。竞争与协作虽然是1v1但本质上涉及对抗性决策能很好地测试模型的策略性。可量化评估胜负、进球数、控球率等指标清晰便于客观比较不同LLM或提示词的效果。这个项目并非要训练一个踢足球的强化学习模型而是评估和激发LLM作为“决策大脑”在模拟环境中的规划与推理能力。2. 环境准备与版本说明我们将基于一个开源复现的框架来搭建环境。为了确保可复现性以下是经过验证的环境配置。2.1 基础运行环境操作系统Ubuntu 20.04/macOS Monterey/Windows 10 (建议使用Linux或macOS进行开发Windows可通过WSL2运行)。Python版本Python 3.9 或 3.10。不推荐使用3.11的某些最新版本以避免潜在的库依赖冲突。包管理工具pip最新版。2.2 核心依赖库我们将创建一个独立的虚拟环境来管理依赖。# 创建并激活虚拟环境以conda为例也可使用venv conda create -n agentic_world_cup python3.9 conda activate agentic_world_cup # 安装核心依赖 pip install openai1.6.1 # 用于调用GPT系列API # 注如果你使用其他LLM API如Anthropic Claude, DeepSeek需安装对应SDK # pip install anthropic # pip install openai # DeepSeek兼容OpenAI API pip install numpy1.24.3 pip install pygame2.5.0 # 用于2D足球环境可视化可选但推荐 pip install pytest7.4.0 # 用于运行测试2.3 LLM API密钥配置本项目核心是LLM你需要准备相应的API密钥。以OpenAI GPT为例访问 OpenAI Platform 创建API Key。在项目根目录创建.env文件避免将密钥硬编码在代码中。# .env 文件内容 OPENAI_API_KEYsk-your-actual-api-key-here # 可选如果你使用其他服务 # ANTHROPIC_API_KEYyour-claude-key # DEEPSEEK_API_KEYyour-deepseek-key # DEEPSEEK_API_BASEhttps://api.deepseek.com/v1 # DeepSeek的API端点在Python代码中使用python-dotenv加载配置pip install python-dotenv1.0.0# config.py import os from dotenv import load_dotenv load_dotenv() OPENAI_API_KEY os.getenv(OPENAI_API_KEY) if not OPENAI_API_KEY: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY)3. 项目架构与核心模块拆解一个典型的Agentic World Cup系统包含以下几个核心模块理解它们有助于我们后续的编码和调试。3.1 环境模拟器 (Environment Simulator)这是足球比赛的“物理引擎”。它定义了状态空间球场尺寸如100x50球的位置(x, y)球员A的位置球员B的位置比分比赛时间等。动作空间球员在每个回合可以执行的动作例如{“move”: “north”},{“shoot”: “towards_goal”},{“pass”: “to_teammate”}在1v1中简化为直接控制。状态转移逻辑根据球员动作、球的位置、物理规则简单的碰撞检测、射门概率计算更新下一时刻的状态。奖励与终止条件进球得1分比赛时间结束或达到最大回合数则终止。3.2 智能体封装器 (Agent Wrapper)这是连接LLM和环境的桥梁。它的核心职责是观察从环境获取当前状态如球员位置、球权、比分。提示工程将状态信息格式化成LLM能理解的提示词Prompt。调用LLM向LLM API发送请求获取其决定的行动。解析与执行解析LLM的返回结果通常是JSON或特定格式文本将其转化为环境能执行的动作指令。3.3 裁判与日志系统 (Referee Logger)裁判判定动作是否合法如是否越位在1v1中可简化计算进球宣布比赛结果。日志系统记录每一回合的状态、LLM的思考过程、最终动作和结果。这对于赛后分析、调试提示词至关重要。3.4 比赛运行器 (Tournament Runner)负责组织多轮比赛让不同的LLM或同一LLM的不同提示词策略相互对抗并统计积分榜。4. 完整实战搭建你的第一届AI世界杯接下来我们分步骤实现一个简化但功能完整的版本。4.1 项目结构创建首先创建清晰的项目目录。agentic_world_cup/ ├── .env # 环境变量API密钥 ├── requirements.txt # 依赖列表 ├── config.py # 配置文件 ├── environment.py # 足球环境模拟器 ├── agent.py # 智能体封装器 ├── referee.py # 裁判与规则 ├── game_runner.py # 单场比赛运行器 ├── tournament.py # 锦标赛运行器 ├── prompts/ # 存放不同策略的提示词 │ └── basic_strategy.txt └── logs/ # 比赛日志4.2 实现足球环境模拟器 (environment.py)我们实现一个非常简化的2D网格足球环境。# environment.py import numpy as np class Soccer1v1Env: def __init__(self, pitch_length100, pitch_width50): self.pitch_length pitch_length self.pitch_width pitch_width self.reset() def reset(self): 重置环境到初始状态 # 球员A初始位置本方半场 self.player_a_pos np.array([self.pitch_length * 0.25, self.pitch_width / 2]) # 球员B初始位置对方半场 self.player_b_pos np.array([self.pitch_length * 0.75, self.pitch_width / 2]) # 球初始位置在中圈 self.ball_pos np.array([self.pitch_length / 2, self.pitch_width / 2]) # 球权0-球员A, 1-球员B self.ball_possession 0 if np.random.rand() 0.5 else 1 # 比分 self.score_a 0 self.score_b 0 # 比赛时间回合数 self.time_step 0 self.max_steps 50 # 一场比赛最多50个回合 self.done False return self._get_state() def _get_state(self): 获取当前环境状态的字典描述用于生成提示词 return { player_a_pos: self.player_a_pos.tolist(), player_b_pos: self.player_b_pos.tolist(), ball_pos: self.ball_pos.tolist(), ball_possession: A if self.ball_possession 0 else B, score: f{self.score_a}-{self.score_b}, time_step: self.time_step, max_steps: self.max_steps, goal_a: (0, self.pitch_width), # A队球门线左 goal_b: (self.pitch_length, self.pitch_width), # B队球门线右 } def step(self, action_a, action_b): 执行球员A和B的动作更新环境 if self.done: raise ValueError(比赛已结束请调用reset()) self.time_step 1 # 1. 处理球员移动简化直接更新位置 self._process_movement(action_a, action_b) # 2. 处理球权与射门 self._process_ball_and_shoot(action_a, action_b) # 3. 检查比赛是否结束 if self.time_step self.max_steps: self.done True # 4. 返回新状态、奖励、结束标志 next_state self._get_state() reward_a 1 if self._check_goal_scored() A else 0 reward_b 1 if self._check_goal_scored() B else 0 # 如果本轮进球重置球到中圈 if reward_a or reward_b: self.ball_pos np.array([self.pitch_length / 2, self.pitch_width / 2]) self.ball_possession 0 if np.random.rand() 0.5 else 1 return next_state, (reward_a, reward_b), self.done def _process_movement(self, action_a, action_b): # 这是一个非常简化的移动逻辑实际可以更复杂 move_speed 5.0 if move in action_a: dir_vec self._parse_direction(action_a[move]) self.player_a_pos dir_vec * move_speed self.player_a_pos np.clip(self.player_a_pos, [0,0], [self.pitch_length, self.pitch_width]) # 同理处理action_b... # 为简洁起见此处省略action_b的处理和越界检查完整代码 def _process_ball_and_shoot(self, action_a, action_b): # 处理射门逻辑如果持球球员选择射门且距离球门足够近则有概率进球 shoot_range 20.0 goal_probability 0.3 if self.ball_possession 0 and shoot in action_a: dist_to_goal_b np.linalg.norm(self.player_a_pos - np.array([self.pitch_length, self.pitch_width/2])) if dist_to_goal_b shoot_range and np.random.rand() goal_probability: self.score_a 1 # 同理处理球员B的射门... # 处理传球/抢断逻辑简化 # ... def _check_goal_scored(self): # 检查上一轮step是否有进球并返回进球方 # 简化实现实际可根据分数变化判断 pass def _parse_direction(self, dir_str): # 将方向字符串解析为向量 dir_map { north: np.array([0, -1]), south: np.array([0, 1]), east: np.array([1, 0]), west: np.array([-1, 0]), } return dir_map.get(dir_str.lower(), np.array([0,0])) def render(self): 可选使用Pygame进行简单可视化 # 此处省略Pygame渲染代码可根据需要实现 pass4.3 实现智能体封装器 (agent.py)这是项目的核心负责与LLM对话。# agent.py import openai from config import OPENAI_API_KEY import json import time class LLMAgent: def __init__(self, name, modelgpt-3.5-turbo, system_prompt_path./prompts/basic_strategy.txt): self.name name self.model model self.client openai.OpenAI(api_keyOPENAI_API_KEY) with open(system_prompt_path, r, encodingutf-8) as f: self.system_prompt f.read() self.conversation_history [] # 可保存历史用于具有记忆的Agent def get_action(self, state): 根据环境状态调用LLM获取动作 # 1. 构建用户提示词将状态信息格式化 user_prompt self._format_state_to_prompt(state) # 2. 调用LLM API try: response self.client.chat.completions.create( modelself.model, messages[ {role: system, content: self.system_prompt}, {role: user, content: user_prompt} ], temperature0.2, # 低温度使输出更稳定、确定性更高 max_tokens150, response_format{ type: json_object } # 强制返回JSON便于解析 ) llm_output response.choices[0].message.content # 3. 解析LLM返回的JSON action json.loads(llm_output) # 4. 记录日志可选 self._log_interaction(state, user_prompt, llm_output, action) return action except (openai.APIError, json.JSONDecodeError) as e: print(fAgent {self.name} 调用LLM失败: {e}返回默认动作) return {move: east} # 失败时返回一个默认动作 def _format_state_to_prompt(self, state): 将环境状态字典转换为LLM能理解的文本提示 prompt f 你正在控制一场1v1足球赛中的球员 {self.name}。 当前比赛状态 - 你的位置{state[player_a_pos] if self.nameA else state[player_b_pos]} - 对手位置{state[player_b_pos] if self.nameA else state[player_a_pos]} - 球的位置{state[ball_pos]} - 当前球权{你 if state[ball_possession] self.name else 对手} - 比分{state[score]} - 比赛时间{state[time_step]}/{state[max_steps]} 你可以执行以下动作之一请以JSON格式回复且只包含一个动作 1. 移动{{move: 方向}}方向可选 north, south, east, west。 2. 射门{{shoot: towards_goal}}仅当你有球权且靠近对方球门时有效。 3. 抢断{{tackle: true}}仅当你无球权且靠近持球对手时有效。 请根据当前状态选择最有利于得分的动作。只返回一个JSON对象。 return prompt def _log_interaction(self, state, prompt, llm_output, action): 记录与LLM的交互用于分析 log_entry { agent: self.name, state: state, prompt: prompt, llm_output: llm_output, action_taken: action, timestamp: time.time() } # 可以写入文件或数据库这里简单打印 print(f[LOG] {log_entry})4.4 实现裁判与单场比赛运行器 (game_runner.py)# game_runner.py from environment import Soccer1v1Env from agent import LLMAgent class GameRunner: def __init__(self, agent_a, agent_b, envNone): self.agent_a agent_a self.agent_b agent_b self.env env if env else Soccer1v1Env() self.log [] def run(self, renderFalse): 运行一场完整的比赛 state self.env.reset() total_reward_a, total_reward_b 0, 0 while not self.env.done: # 1. 智能体根据状态决策 action_a self.agent_a.get_action(state) action_b self.agent_b.get_action(state) # 2. 环境执行动作更新状态 next_state, (reward_a, reward_b), done self.env.step(action_a, action_b) # 3. 记录回合信息 self.log.append({ step: self.env.time_step, state: state, action_a: action_a, action_b: action_b, reward_a: reward_a, reward_b: reward_b, next_state: next_state }) total_reward_a reward_a total_reward_b reward_b state next_state # 4. 可选可视化 if render: self.env.render() # 比赛结束 winner A if total_reward_a total_reward_b else (B if total_reward_b total_reward_a else Draw) result { score: f{self.env.score_a}-{self.env.score_b}, winner: winner, total_rewards: (total_reward_a, total_reward_b), log: self.log } print(f比赛结束比分{result[score]}胜者{result[winner]}) return result4.5 组织锦标赛并运行 (tournament.py)# tournament.py from agent import LLMAgent from game_runner import GameRunner import pandas as pd class Tournament: def __init__(self, agent_configs): agent_configs: 列表每个元素是包含name和model等信息的字典 例如[{name:GPT-4, model:gpt-4}, {name:Claude-3, model:claude-3-sonnet}] self.agents {cfg[name]: LLMAgent(**cfg) for cfg in agent_configs} self.agent_names list(self.agents.keys()) self.results [] # 存储每场比赛结果 self.standings {name: {wins:0, draws:0, losses:0, goals_for:0, goals_against:0} for name in self.agent_names} def run_round_robin(self, matches_per_pair1): 循环赛制 for i, name_a in enumerate(self.agent_names): for name_b in self.agent_names[i1:]: for match in range(matches_per_pair): print(f\n 比赛开始{name_a} vs {name_b} (第{match1}场) ) runner GameRunner(self.agents[name_a], self.agents[name_b]) result runner.run(renderFalse) # 正式比赛可关闭渲染提升速度 result[player_a] name_a result[player_b] name_b self.results.append(result) # 更新积分榜 self._update_standings(name_a, name_b, result) def _update_standings(self, name_a, name_b, result): score_a, score_b map(int, result[score].split(-)) self.standings[name_a][goals_for] score_a self.standings[name_a][goals_against] score_b self.standings[name_b][goals_for] score_b self.standings[name_b][goals_against] score_a if result[winner] A: self.standings[name_a][wins] 1 self.standings[name_b][losses] 1 elif result[winner] B: self.standings[name_b][wins] 1 self.standings[name_a][losses] 1 else: # Draw self.standings[name_a][draws] 1 self.standings[name_b][draws] 1 def display_standings(self): 显示积分榜 df pd.DataFrame.from_dict(self.standings, orientindex) df[points] df[wins] * 3 df[draws] * 1 df[goal_diff] df[goals_for] - df[goals_against] df df.sort_values([points, goal_diff, goals_for], ascendingFalse) print(\n 最终积分榜 ) print(df) # 主程序入口 if __name__ __main__: # 配置参赛智能体可以使用不同模型或相同模型不同提示词 agents [ {name: GPT-4-Turbo, model: gpt-4-turbo-preview, system_prompt_path: ./prompts/aggressive.txt}, {name: GPT-3.5-Turbo, model: gpt-3.5-turbo, system_prompt_path: ./prompts/balanced.txt}, # {name: Claude-3-Haiku, model: claude-3-haiku-20240307}, # 需安装anthropic库并配置API_KEY ] tournament Tournament(agents) tournament.run_round_robin(matches_per_pair2) # 每对组合比赛2场 tournament.display_standings()4.6 编写提示词 (prompts/balanced.txt)提示词的质量直接决定智能体的“球商”。你是一个1v1足球比赛的AI球员。你的目标是进球并赢得比赛。 核心策略 1. 当你有球权时 - 优先考虑向对方球门方向移动东边。 - 如果你离对方球门很近例如距离20尝试射门。 - 如果对手靠近你可以考虑横向移动北或南以摆脱。 2. 当你没有球权时 - 快速靠近持球的对手。 - 当足够接近时尝试抢断。 3. 始终注意比赛时间。如果临近结束且平分要采取更冒险的策略。 4. 你的回复必须是且仅是一个有效的JSON对象格式如 {move: east} 或 {shoot: towards_goal} 或 {tackle: true}。 不要添加任何解释性文字。你可以创建多个提示词文件如aggressive.txt,defensive.txt来赋予智能体不同的策略风格。4.7 运行你的世界杯确保所有文件就位.env配置正确。安装所有依赖pip install -r requirements.txt。运行锦标赛python tournament.py观察控制台输出查看激烈的AI足球赛况和最终积分榜5. 常见问题与排查思路在实现和运行过程中你可能会遇到以下问题问题现象可能原因解决思路ModuleNotFoundError: No module named openai依赖未安装或虚拟环境未激活。1. 确认已激活虚拟环境 (conda activate agentic_world_cup)。2. 运行pip install -r requirements.txt或手动安装缺失包。openai.AuthenticationErrorAPI密钥无效或未设置。1. 检查.env文件是否存在且OPENAI_API_KEY值正确。2. 确保在代码中正确加载了.env文件 (load_dotenv())。3. 检查API密钥是否有余额或权限。LLM返回非JSON格式导致json.JSONDecodeError提示词未强制要求JSON格式或LLM“不听话”。1. 在系统提示词中明确要求“只返回JSON”。2. 使用OpenAI API的response_format{ type: json_object }参数仅部分最新模型支持。3. 在代码中添加健壮的解析逻辑尝试提取JSON部分或提供默认动作。智能体行为愚蠢一直在原地转圈或做无效动作提示词不够清晰或状态信息表达不充分。1. 优化提示词给出更具体、可操作的战略指导。2. 在状态描述中加入更关键的决策信息如“距离对方球门的距离”。3. 在_format_state_to_prompt函数中以更直观的方式如相对位置描述状态。比赛运行速度极慢每回合都调用LLM API网络延迟高。1. 考虑使用更快的模型如gpt-3.5-turbo。2. 实现简单的本地缓存对相似状态返回缓存动作需谨慎可能影响策略。3. 增加每回合的决策时间间隔或批量处理请求如果API支持。4.本地模型对于实验可使用本地部署的轻量级LLM如Llama 3.2 3B Instruct通过ollama或vLLM提供兼容OpenAI的API。AttributeError: ‘Soccer1v1Env’ object has no attribute ‘done’环境类中的属性名不一致。检查environment.py中是否使用self.done作为结束标志并在step方法中正确更新它。确保reset()方法对其初始化。6. 最佳实践与工程优化建议要让你的Agentic World Cup更稳定、更高效、更具研究价值可以参考以下进阶实践6.1 提示词工程优化角色扮演让LLM扮演特定风格的球员如“梅西”、“防守型中场”观察其行为变化。链式思考 (CoT)在提示词中要求模型“先简要推理再输出动作”这能显著提升决策质量。例如在用户提示词末尾加上“请先简要说明你的决策理由然后输出JSON动作。”少样本学习 (Few-Shot)在提示词中提供几个状态-动作的优秀示例引导LLM学习有效策略。6.2 系统架构优化异步并发使用asyncio和aiohttp并发调用多个LLM API极大提升锦标赛运行速度。状态抽象不要将原始坐标直接丢给LLM。将其抽象为更高层次的概念如“你在对方半场”、“球在禁区附近”、“你正面对对手”能降低LLM的理解负担。记忆与反思为智能体添加短期记忆保存最近N个回合的状态-动作对并在提示词中让其总结对手的战术模式实现自适应。6.3 评估与实验管理系统化日志不要只打印日志应将每场比赛的完整轨迹状态、动作、奖励保存为结构化文件如JSONL或数据库便于后续分析。可视化分析开发一个简单的Web面板或使用streamlit可视化展示比赛回放、智能体的决策热点图、胜率统计等。控制变量实验科学地比较不同因素模型、提示词、温度参数的影响。例如固定其他条件只改变提示词策略运行多次比赛统计胜率。6.4 成本与性能考量本地模型替代对于大规模实验API调用成本可能很高。考虑使用ollama本地运行llama3.2、qwen2.5等开源模型并通过其提供的兼容OpenAI的API端点接入成本极低。请求缓存对完全相同的状态提示词可以缓存LLM的响应避免重复计算。简化环境如果只为测试核心的Agentic能力可以进一步简化环境如更小的网格、更少的动作以减少每个回合的状态描述长度从而降低Token消耗。通过这个项目你不仅搭建了一个有趣的AI竞技场更深入实践了Agentic AI的核心流程感知 - 规划 - 执行 - 学习通过提示词迭代。你可以在此基础上无限扩展增加更多球员2v2、引入更复杂的物理规则、连接真实的足球游戏模拟器如Google Research Football甚至让智能体通过强化学习来自我改进。这为理解和开发更强大的自主AI系统提供了一个绝佳的起点。 从零搭建AI足球世界杯：基于LLM的Agentic智能体实战指南
最近在探索AI Agent的落地场景时发现很多演示都停留在简单的问答或工具调用上缺乏动态、连续决策的复杂环境。这让我思考能否构建一个更“好玩”、更能体现智能体自主决策能力的竞技场受此启发我们团队尝试复现并深度解析了Hacker News上热议的“Agentic World Cup”项目——一个让大型语言模型LLM在1v1足球模拟环境中自主对抗的竞赛平台。本文将带你从零开始深入理解其架构并手把手教你搭建自己的“AI足球联赛”体验LLM在动态环境中的策略博弈。本文适合对AI Agent、多智能体系统、LLM应用开发感兴趣的开发者。无论你是想了解Agentic设计模式还是希望为你的LLM寻找一个有趣的评估沙盒都能在这里找到完整的代码、配置与实战经验。我们将覆盖从环境搭建、智能体设计、比赛运行到结果分析的完整闭环。1. 背景与核心概念为什么是“AI足球”在深入代码之前我们首先要厘清几个关键概念并理解这个项目背后的意义。1.1 什么是 Agentic AI“Agentic”一词源于“Agent”智能体它描述的是一种能够感知环境、自主设定目标、制定并执行计划以达成目标的AI系统。与传统的一次性问答不同Agentic AI强调持续性、目标导向性和工具使用能力。一个Agentic LLM不仅会回答问题还会在长期任务中分解步骤、使用外部工具如搜索、计算、执行代码并适应环境变化。1.2 从传统RAG到Agentic RAG的演进搜索热词中提到了“从传统RAG到Agentic RAG的进阶优化”。这揭示了当前的一个技术趋势传统RAG (Retrieval-Augmented Generation)主要用于增强LLM的知识通过检索相关文档来生成更准确的答案。它是一个被动的、响应式的系统。Agentic RAG将RAG能力嵌入到一个主动的智能体中。智能体可以主动决定何时进行检索、检索什么、如何利用检索到的信息来推进一个多步骤的任务。这体现了“Agentic”的自主决策特性。我们的足球Agent就是一个简化版的Agentic系统它需要根据球场状态环境主动决定行动如传球、射门以达成进球的目标。1.3 项目核心价值一个理想的智能体测试床为什么选择足球作为测试场景动态环境球场状态瞬息万变要求智能体进行实时感知和决策。长期规划从后场组织到前场射门需要多步连贯的策略而非单次反应。竞争与协作虽然是1v1但本质上涉及对抗性决策能很好地测试模型的策略性。可量化评估胜负、进球数、控球率等指标清晰便于客观比较不同LLM或提示词的效果。这个项目并非要训练一个踢足球的强化学习模型而是评估和激发LLM作为“决策大脑”在模拟环境中的规划与推理能力。2. 环境准备与版本说明我们将基于一个开源复现的框架来搭建环境。为了确保可复现性以下是经过验证的环境配置。2.1 基础运行环境操作系统Ubuntu 20.04/macOS Monterey/Windows 10 (建议使用Linux或macOS进行开发Windows可通过WSL2运行)。Python版本Python 3.9 或 3.10。不推荐使用3.11的某些最新版本以避免潜在的库依赖冲突。包管理工具pip最新版。2.2 核心依赖库我们将创建一个独立的虚拟环境来管理依赖。# 创建并激活虚拟环境以conda为例也可使用venv conda create -n agentic_world_cup python3.9 conda activate agentic_world_cup # 安装核心依赖 pip install openai1.6.1 # 用于调用GPT系列API # 注如果你使用其他LLM API如Anthropic Claude, DeepSeek需安装对应SDK # pip install anthropic # pip install openai # DeepSeek兼容OpenAI API pip install numpy1.24.3 pip install pygame2.5.0 # 用于2D足球环境可视化可选但推荐 pip install pytest7.4.0 # 用于运行测试2.3 LLM API密钥配置本项目核心是LLM你需要准备相应的API密钥。以OpenAI GPT为例访问 OpenAI Platform 创建API Key。在项目根目录创建.env文件避免将密钥硬编码在代码中。# .env 文件内容 OPENAI_API_KEYsk-your-actual-api-key-here # 可选如果你使用其他服务 # ANTHROPIC_API_KEYyour-claude-key # DEEPSEEK_API_KEYyour-deepseek-key # DEEPSEEK_API_BASEhttps://api.deepseek.com/v1 # DeepSeek的API端点在Python代码中使用python-dotenv加载配置pip install python-dotenv1.0.0# config.py import os from dotenv import load_dotenv load_dotenv() OPENAI_API_KEY os.getenv(OPENAI_API_KEY) if not OPENAI_API_KEY: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY)3. 项目架构与核心模块拆解一个典型的Agentic World Cup系统包含以下几个核心模块理解它们有助于我们后续的编码和调试。3.1 环境模拟器 (Environment Simulator)这是足球比赛的“物理引擎”。它定义了状态空间球场尺寸如100x50球的位置(x, y)球员A的位置球员B的位置比分比赛时间等。动作空间球员在每个回合可以执行的动作例如{“move”: “north”},{“shoot”: “towards_goal”},{“pass”: “to_teammate”}在1v1中简化为直接控制。状态转移逻辑根据球员动作、球的位置、物理规则简单的碰撞检测、射门概率计算更新下一时刻的状态。奖励与终止条件进球得1分比赛时间结束或达到最大回合数则终止。3.2 智能体封装器 (Agent Wrapper)这是连接LLM和环境的桥梁。它的核心职责是观察从环境获取当前状态如球员位置、球权、比分。提示工程将状态信息格式化成LLM能理解的提示词Prompt。调用LLM向LLM API发送请求获取其决定的行动。解析与执行解析LLM的返回结果通常是JSON或特定格式文本将其转化为环境能执行的动作指令。3.3 裁判与日志系统 (Referee Logger)裁判判定动作是否合法如是否越位在1v1中可简化计算进球宣布比赛结果。日志系统记录每一回合的状态、LLM的思考过程、最终动作和结果。这对于赛后分析、调试提示词至关重要。3.4 比赛运行器 (Tournament Runner)负责组织多轮比赛让不同的LLM或同一LLM的不同提示词策略相互对抗并统计积分榜。4. 完整实战搭建你的第一届AI世界杯接下来我们分步骤实现一个简化但功能完整的版本。4.1 项目结构创建首先创建清晰的项目目录。agentic_world_cup/ ├── .env # 环境变量API密钥 ├── requirements.txt # 依赖列表 ├── config.py # 配置文件 ├── environment.py # 足球环境模拟器 ├── agent.py # 智能体封装器 ├── referee.py # 裁判与规则 ├── game_runner.py # 单场比赛运行器 ├── tournament.py # 锦标赛运行器 ├── prompts/ # 存放不同策略的提示词 │ └── basic_strategy.txt └── logs/ # 比赛日志4.2 实现足球环境模拟器 (environment.py)我们实现一个非常简化的2D网格足球环境。# environment.py import numpy as np class Soccer1v1Env: def __init__(self, pitch_length100, pitch_width50): self.pitch_length pitch_length self.pitch_width pitch_width self.reset() def reset(self): 重置环境到初始状态 # 球员A初始位置本方半场 self.player_a_pos np.array([self.pitch_length * 0.25, self.pitch_width / 2]) # 球员B初始位置对方半场 self.player_b_pos np.array([self.pitch_length * 0.75, self.pitch_width / 2]) # 球初始位置在中圈 self.ball_pos np.array([self.pitch_length / 2, self.pitch_width / 2]) # 球权0-球员A, 1-球员B self.ball_possession 0 if np.random.rand() 0.5 else 1 # 比分 self.score_a 0 self.score_b 0 # 比赛时间回合数 self.time_step 0 self.max_steps 50 # 一场比赛最多50个回合 self.done False return self._get_state() def _get_state(self): 获取当前环境状态的字典描述用于生成提示词 return { player_a_pos: self.player_a_pos.tolist(), player_b_pos: self.player_b_pos.tolist(), ball_pos: self.ball_pos.tolist(), ball_possession: A if self.ball_possession 0 else B, score: f{self.score_a}-{self.score_b}, time_step: self.time_step, max_steps: self.max_steps, goal_a: (0, self.pitch_width), # A队球门线左 goal_b: (self.pitch_length, self.pitch_width), # B队球门线右 } def step(self, action_a, action_b): 执行球员A和B的动作更新环境 if self.done: raise ValueError(比赛已结束请调用reset()) self.time_step 1 # 1. 处理球员移动简化直接更新位置 self._process_movement(action_a, action_b) # 2. 处理球权与射门 self._process_ball_and_shoot(action_a, action_b) # 3. 检查比赛是否结束 if self.time_step self.max_steps: self.done True # 4. 返回新状态、奖励、结束标志 next_state self._get_state() reward_a 1 if self._check_goal_scored() A else 0 reward_b 1 if self._check_goal_scored() B else 0 # 如果本轮进球重置球到中圈 if reward_a or reward_b: self.ball_pos np.array([self.pitch_length / 2, self.pitch_width / 2]) self.ball_possession 0 if np.random.rand() 0.5 else 1 return next_state, (reward_a, reward_b), self.done def _process_movement(self, action_a, action_b): # 这是一个非常简化的移动逻辑实际可以更复杂 move_speed 5.0 if move in action_a: dir_vec self._parse_direction(action_a[move]) self.player_a_pos dir_vec * move_speed self.player_a_pos np.clip(self.player_a_pos, [0,0], [self.pitch_length, self.pitch_width]) # 同理处理action_b... # 为简洁起见此处省略action_b的处理和越界检查完整代码 def _process_ball_and_shoot(self, action_a, action_b): # 处理射门逻辑如果持球球员选择射门且距离球门足够近则有概率进球 shoot_range 20.0 goal_probability 0.3 if self.ball_possession 0 and shoot in action_a: dist_to_goal_b np.linalg.norm(self.player_a_pos - np.array([self.pitch_length, self.pitch_width/2])) if dist_to_goal_b shoot_range and np.random.rand() goal_probability: self.score_a 1 # 同理处理球员B的射门... # 处理传球/抢断逻辑简化 # ... def _check_goal_scored(self): # 检查上一轮step是否有进球并返回进球方 # 简化实现实际可根据分数变化判断 pass def _parse_direction(self, dir_str): # 将方向字符串解析为向量 dir_map { north: np.array([0, -1]), south: np.array([0, 1]), east: np.array([1, 0]), west: np.array([-1, 0]), } return dir_map.get(dir_str.lower(), np.array([0,0])) def render(self): 可选使用Pygame进行简单可视化 # 此处省略Pygame渲染代码可根据需要实现 pass4.3 实现智能体封装器 (agent.py)这是项目的核心负责与LLM对话。# agent.py import openai from config import OPENAI_API_KEY import json import time class LLMAgent: def __init__(self, name, modelgpt-3.5-turbo, system_prompt_path./prompts/basic_strategy.txt): self.name name self.model model self.client openai.OpenAI(api_keyOPENAI_API_KEY) with open(system_prompt_path, r, encodingutf-8) as f: self.system_prompt f.read() self.conversation_history [] # 可保存历史用于具有记忆的Agent def get_action(self, state): 根据环境状态调用LLM获取动作 # 1. 构建用户提示词将状态信息格式化 user_prompt self._format_state_to_prompt(state) # 2. 调用LLM API try: response self.client.chat.completions.create( modelself.model, messages[ {role: system, content: self.system_prompt}, {role: user, content: user_prompt} ], temperature0.2, # 低温度使输出更稳定、确定性更高 max_tokens150, response_format{ type: json_object } # 强制返回JSON便于解析 ) llm_output response.choices[0].message.content # 3. 解析LLM返回的JSON action json.loads(llm_output) # 4. 记录日志可选 self._log_interaction(state, user_prompt, llm_output, action) return action except (openai.APIError, json.JSONDecodeError) as e: print(fAgent {self.name} 调用LLM失败: {e}返回默认动作) return {move: east} # 失败时返回一个默认动作 def _format_state_to_prompt(self, state): 将环境状态字典转换为LLM能理解的文本提示 prompt f 你正在控制一场1v1足球赛中的球员 {self.name}。 当前比赛状态 - 你的位置{state[player_a_pos] if self.nameA else state[player_b_pos]} - 对手位置{state[player_b_pos] if self.nameA else state[player_a_pos]} - 球的位置{state[ball_pos]} - 当前球权{你 if state[ball_possession] self.name else 对手} - 比分{state[score]} - 比赛时间{state[time_step]}/{state[max_steps]} 你可以执行以下动作之一请以JSON格式回复且只包含一个动作 1. 移动{{move: 方向}}方向可选 north, south, east, west。 2. 射门{{shoot: towards_goal}}仅当你有球权且靠近对方球门时有效。 3. 抢断{{tackle: true}}仅当你无球权且靠近持球对手时有效。 请根据当前状态选择最有利于得分的动作。只返回一个JSON对象。 return prompt def _log_interaction(self, state, prompt, llm_output, action): 记录与LLM的交互用于分析 log_entry { agent: self.name, state: state, prompt: prompt, llm_output: llm_output, action_taken: action, timestamp: time.time() } # 可以写入文件或数据库这里简单打印 print(f[LOG] {log_entry})4.4 实现裁判与单场比赛运行器 (game_runner.py)# game_runner.py from environment import Soccer1v1Env from agent import LLMAgent class GameRunner: def __init__(self, agent_a, agent_b, envNone): self.agent_a agent_a self.agent_b agent_b self.env env if env else Soccer1v1Env() self.log [] def run(self, renderFalse): 运行一场完整的比赛 state self.env.reset() total_reward_a, total_reward_b 0, 0 while not self.env.done: # 1. 智能体根据状态决策 action_a self.agent_a.get_action(state) action_b self.agent_b.get_action(state) # 2. 环境执行动作更新状态 next_state, (reward_a, reward_b), done self.env.step(action_a, action_b) # 3. 记录回合信息 self.log.append({ step: self.env.time_step, state: state, action_a: action_a, action_b: action_b, reward_a: reward_a, reward_b: reward_b, next_state: next_state }) total_reward_a reward_a total_reward_b reward_b state next_state # 4. 可选可视化 if render: self.env.render() # 比赛结束 winner A if total_reward_a total_reward_b else (B if total_reward_b total_reward_a else Draw) result { score: f{self.env.score_a}-{self.env.score_b}, winner: winner, total_rewards: (total_reward_a, total_reward_b), log: self.log } print(f比赛结束比分{result[score]}胜者{result[winner]}) return result4.5 组织锦标赛并运行 (tournament.py)# tournament.py from agent import LLMAgent from game_runner import GameRunner import pandas as pd class Tournament: def __init__(self, agent_configs): agent_configs: 列表每个元素是包含name和model等信息的字典 例如[{name:GPT-4, model:gpt-4}, {name:Claude-3, model:claude-3-sonnet}] self.agents {cfg[name]: LLMAgent(**cfg) for cfg in agent_configs} self.agent_names list(self.agents.keys()) self.results [] # 存储每场比赛结果 self.standings {name: {wins:0, draws:0, losses:0, goals_for:0, goals_against:0} for name in self.agent_names} def run_round_robin(self, matches_per_pair1): 循环赛制 for i, name_a in enumerate(self.agent_names): for name_b in self.agent_names[i1:]: for match in range(matches_per_pair): print(f\n 比赛开始{name_a} vs {name_b} (第{match1}场) ) runner GameRunner(self.agents[name_a], self.agents[name_b]) result runner.run(renderFalse) # 正式比赛可关闭渲染提升速度 result[player_a] name_a result[player_b] name_b self.results.append(result) # 更新积分榜 self._update_standings(name_a, name_b, result) def _update_standings(self, name_a, name_b, result): score_a, score_b map(int, result[score].split(-)) self.standings[name_a][goals_for] score_a self.standings[name_a][goals_against] score_b self.standings[name_b][goals_for] score_b self.standings[name_b][goals_against] score_a if result[winner] A: self.standings[name_a][wins] 1 self.standings[name_b][losses] 1 elif result[winner] B: self.standings[name_b][wins] 1 self.standings[name_a][losses] 1 else: # Draw self.standings[name_a][draws] 1 self.standings[name_b][draws] 1 def display_standings(self): 显示积分榜 df pd.DataFrame.from_dict(self.standings, orientindex) df[points] df[wins] * 3 df[draws] * 1 df[goal_diff] df[goals_for] - df[goals_against] df df.sort_values([points, goal_diff, goals_for], ascendingFalse) print(\n 最终积分榜 ) print(df) # 主程序入口 if __name__ __main__: # 配置参赛智能体可以使用不同模型或相同模型不同提示词 agents [ {name: GPT-4-Turbo, model: gpt-4-turbo-preview, system_prompt_path: ./prompts/aggressive.txt}, {name: GPT-3.5-Turbo, model: gpt-3.5-turbo, system_prompt_path: ./prompts/balanced.txt}, # {name: Claude-3-Haiku, model: claude-3-haiku-20240307}, # 需安装anthropic库并配置API_KEY ] tournament Tournament(agents) tournament.run_round_robin(matches_per_pair2) # 每对组合比赛2场 tournament.display_standings()4.6 编写提示词 (prompts/balanced.txt)提示词的质量直接决定智能体的“球商”。你是一个1v1足球比赛的AI球员。你的目标是进球并赢得比赛。 核心策略 1. 当你有球权时 - 优先考虑向对方球门方向移动东边。 - 如果你离对方球门很近例如距离20尝试射门。 - 如果对手靠近你可以考虑横向移动北或南以摆脱。 2. 当你没有球权时 - 快速靠近持球的对手。 - 当足够接近时尝试抢断。 3. 始终注意比赛时间。如果临近结束且平分要采取更冒险的策略。 4. 你的回复必须是且仅是一个有效的JSON对象格式如 {move: east} 或 {shoot: towards_goal} 或 {tackle: true}。 不要添加任何解释性文字。你可以创建多个提示词文件如aggressive.txt,defensive.txt来赋予智能体不同的策略风格。4.7 运行你的世界杯确保所有文件就位.env配置正确。安装所有依赖pip install -r requirements.txt。运行锦标赛python tournament.py观察控制台输出查看激烈的AI足球赛况和最终积分榜5. 常见问题与排查思路在实现和运行过程中你可能会遇到以下问题问题现象可能原因解决思路ModuleNotFoundError: No module named openai依赖未安装或虚拟环境未激活。1. 确认已激活虚拟环境 (conda activate agentic_world_cup)。2. 运行pip install -r requirements.txt或手动安装缺失包。openai.AuthenticationErrorAPI密钥无效或未设置。1. 检查.env文件是否存在且OPENAI_API_KEY值正确。2. 确保在代码中正确加载了.env文件 (load_dotenv())。3. 检查API密钥是否有余额或权限。LLM返回非JSON格式导致json.JSONDecodeError提示词未强制要求JSON格式或LLM“不听话”。1. 在系统提示词中明确要求“只返回JSON”。2. 使用OpenAI API的response_format{ type: json_object }参数仅部分最新模型支持。3. 在代码中添加健壮的解析逻辑尝试提取JSON部分或提供默认动作。智能体行为愚蠢一直在原地转圈或做无效动作提示词不够清晰或状态信息表达不充分。1. 优化提示词给出更具体、可操作的战略指导。2. 在状态描述中加入更关键的决策信息如“距离对方球门的距离”。3. 在_format_state_to_prompt函数中以更直观的方式如相对位置描述状态。比赛运行速度极慢每回合都调用LLM API网络延迟高。1. 考虑使用更快的模型如gpt-3.5-turbo。2. 实现简单的本地缓存对相似状态返回缓存动作需谨慎可能影响策略。3. 增加每回合的决策时间间隔或批量处理请求如果API支持。4.本地模型对于实验可使用本地部署的轻量级LLM如Llama 3.2 3B Instruct通过ollama或vLLM提供兼容OpenAI的API。AttributeError: ‘Soccer1v1Env’ object has no attribute ‘done’环境类中的属性名不一致。检查environment.py中是否使用self.done作为结束标志并在step方法中正确更新它。确保reset()方法对其初始化。6. 最佳实践与工程优化建议要让你的Agentic World Cup更稳定、更高效、更具研究价值可以参考以下进阶实践6.1 提示词工程优化角色扮演让LLM扮演特定风格的球员如“梅西”、“防守型中场”观察其行为变化。链式思考 (CoT)在提示词中要求模型“先简要推理再输出动作”这能显著提升决策质量。例如在用户提示词末尾加上“请先简要说明你的决策理由然后输出JSON动作。”少样本学习 (Few-Shot)在提示词中提供几个状态-动作的优秀示例引导LLM学习有效策略。6.2 系统架构优化异步并发使用asyncio和aiohttp并发调用多个LLM API极大提升锦标赛运行速度。状态抽象不要将原始坐标直接丢给LLM。将其抽象为更高层次的概念如“你在对方半场”、“球在禁区附近”、“你正面对对手”能降低LLM的理解负担。记忆与反思为智能体添加短期记忆保存最近N个回合的状态-动作对并在提示词中让其总结对手的战术模式实现自适应。6.3 评估与实验管理系统化日志不要只打印日志应将每场比赛的完整轨迹状态、动作、奖励保存为结构化文件如JSONL或数据库便于后续分析。可视化分析开发一个简单的Web面板或使用streamlit可视化展示比赛回放、智能体的决策热点图、胜率统计等。控制变量实验科学地比较不同因素模型、提示词、温度参数的影响。例如固定其他条件只改变提示词策略运行多次比赛统计胜率。6.4 成本与性能考量本地模型替代对于大规模实验API调用成本可能很高。考虑使用ollama本地运行llama3.2、qwen2.5等开源模型并通过其提供的兼容OpenAI的API端点接入成本极低。请求缓存对完全相同的状态提示词可以缓存LLM的响应避免重复计算。简化环境如果只为测试核心的Agentic能力可以进一步简化环境如更小的网格、更少的动作以减少每个回合的状态描述长度从而降低Token消耗。通过这个项目你不仅搭建了一个有趣的AI竞技场更深入实践了Agentic AI的核心流程感知 - 规划 - 执行 - 学习通过提示词迭代。你可以在此基础上无限扩展增加更多球员2v2、引入更复杂的物理规则、连接真实的足球游戏模拟器如Google Research Football甚至让智能体通过强化学习来自我改进。这为理解和开发更强大的自主AI系统提供了一个绝佳的起点。