AgentSociety 部署实战：从环境准备到场景落地的完整指南

项目核心价值与应用场景

AgentSociety作为基于大语言模型的大规模社会模拟平台，通过LLM驱动的智能体网络构建了一个微观行为与宏观现象相互作用的研究工具。其核心价值体现在三个维度：行为机制解析（通过可解释的智能体决策过程理解社会行为规律）、政策模拟推演（在虚拟环境中测试政策效果）、复杂系统涌现（观察多智能体交互产生的突现现象）。

该平台已被应用于社会冲突模拟、公共政策评估、群体行为预测等研究领域，支持从微观个体决策到宏观社会现象的跨尺度分析。例如在灾害响应研究中，可模拟飓风等突发事件下的人群疏散路径与资源分配策略；在经济政策领域，能通过市民智能体的消费行为变化评估UBI（全民基本收入）政策的潜在影响。

AgentSociety架构概览 - 展示核心模块包括社会智能体、社会环境、大规模交互及典型应用场景

环境兼容性与预检查清单

系统环境要求

硬件配置基线：

• CPU：4核及以上（推荐8核+以支持并行模拟）
• 内存：16GB RAM（大规模模拟建议32GB+）
• 存储：10GB可用空间（含依赖包、模型缓存和模拟数据）

软件环境要求：

• 操作系统：Linux X86_64（Ubuntu 20.04+/CentOS 8+）或 macOS ARM
• Python版本：3.11.x（3.11.4+推荐，需包含pip包管理工具）
• 网络环境：可访问PyPI仓库及LLM API服务（需开放443端口）

预检查清单

在开始部署前，请通过以下命令验证环境：

# 检查Python版本
python --version  # 应输出Python 3.11.x

# 检查pip版本
pip --version     # 确保pip 22.0+

# 检查系统架构
uname -m          # Linux应显示x86_64，macOS显示arm64

# 检查网络连通性
curl -I https://pypi.org  # 应返回200 OK

⚠️ 兼容性警告：Windows系统不直接支持，需通过WSL 2安装Ubuntu子系统；macOS Intel芯片需额外安装Rosetta 2转译层。

分步骤部署教程

1. 源码获取与环境准备

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/ag/agentsociety
cd agentsociety

# 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows (WSL环境仍使用Linux命令)

# 升级依赖管理工具
pip install --upgrade pip setuptools wheel

2. 核心组件安装

# 安装核心包
pip install .

# 安装社区扩展与基准测试工具（可选）
pip install agentsociety-community agentsociety-benchmark

💡 安装加速技巧：国内用户可添加PyPI镜像源加速安装：

pip install . -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 配置文件准备

# 复制配置模板
cp examples/config_templates/example_config.yaml ./my_config.yaml

使用文本编辑器打开my_config.yaml，关键配置项说明：

# LLM配置（核心必选）
llm:
  - api_key: "your_api_key_here"  # 替换为实际API密钥
    base_url: "https://api.openai.com/v1"  # API基础地址
    model: "gpt-4o"  # 模型名称
    provider: "openai"  # 服务提供商
    semaphore: 200  # 并发请求控制（根据API配额调整）

# 环境配置
env:
  db:
    enabled: true  # 启用数据库记录模拟数据
    db_type: "sqlite"  # 开发环境建议使用sqlite，生产环境可切换为postgresql

# 地图配置
map:
  file_path: "./map_data/city.geojson"  # 地图数据文件路径（需单独下载）

# 智能体配置
agents:
  citizens:
    - agent_class: "citizen"  # 智能体类型
      number: 100  # 智能体数量（初学者建议从10-50开始）

4. 数据库初始化（可选）

对于需要持久化存储模拟结果的场景，初始化数据库：

# 生成数据库表结构
agentsociety db init --config my_config.yaml

⚠️ 注意：首次运行会在当前目录创建agentsociety_data文件夹，包含数据库文件和模拟日志。

5. WebUI启动与访问

# 创建WebUI配置文件
cat > ui_config.yaml << EOF
addr: 0.0.0.0:8080  # 绑定所有网络接口，允许外部访问
env:
  db:
    enabled: true
    db_type: sqlite
  home_dir: ./agentsociety_data
EOF

# 启动WebUI
agentsociety ui -c ui_config.yaml

启动成功后，通过浏览器访问 http://服务器IP:8080 进入Web管理界面。

功能验证方法

基础功能验证

# 检查CLI工具是否正常工作
agentsociety --version

# 运行配置预检查
agentsociety check -c my_config.yaml

成功输出示例：

✅ Config validation passed
✅ LLM API connection test successful
✅ Map file loaded (1256 entities)
✅ Database connection established

WebUI功能验证

1. LLM配置验证：登录WebUI后，进入"配置管理" → "LLM设置"，点击"测试连接"按钮验证API可用性

2. 模拟实验创建：

   • 进入"实验管理" → "创建实验"
   • 填写实验名称，选择智能体模板
   • 配置模拟时长（建议从1天=1440分钟开始）
   • 点击"启动模拟"

3. 结果查看：模拟运行后，在"实验详情"页面可查看：

   • 智能体分布热力图
   • 关键指标变化曲线
   • 智能体交互日志

LLM API配置界面 - 支持多提供商配置、并发控制和连接测试

典型应用场景配置

场景一：城市灾害响应模拟

# 灾害响应模拟配置示例
exp:
  name: "hurricane_evacuation"
  description: "模拟飓风来临前的城市疏散行为"
  environment:
    start_tick: 28800  # 从早上8点开始（分钟数）
    weather: "hurricane"  # 启用灾害天气模块
  agents:
    citizens:
      - agent_class: "citizen"
        number: 500
        profile: "profiles/hurricane_evacuation.json"  # 灾害响应特征画像
  workflow:
    - day: 1
      type: "normal"  # 正常生活模式
    - day: 2
      type: "hurricane_warning"  # 发布飓风预警
    - day: 3
      type: "evacuation_order"  # 发布疏散命令

场景二：社会舆论传播模拟

# 舆论传播模拟配置示例
exp:
  name: "misinformation_spread"
  environment:
    social_media: true  # 启用社交媒体模块
    media_bias: 0.3  # 媒体偏向性系数
  agents:
    citizens:
      - agent_class: "citizen"
        number: 1000
        personality: "diverse"  # 多样化人格特征
    media_agents:
      - agent_class: "media"
        number: 5  # 媒体智能体数量
  messages:
    initial: "rumor.json"  # 初始谣言内容
    spread_rate: 0.7  # 消息传播概率

性能优化建议

1. LLM调用优化：

   • 启用本地缓存：在配置文件中添加cache: true
   • 批量处理请求：将semaphore设置为API允许的最大并发数
   • 模型分级使用：简单任务使用轻量级模型（如gpt-3.5-turbo）

2. 计算资源分配：

   • 智能体数量与CPU核心比建议为100:1
   • 内存分配：每个智能体约需100MB内存
   • 对于1000+智能体模拟，建议使用分布式部署

3. 数据存储优化：

   • 生产环境切换至PostgreSQL数据库
   • 设置模拟数据自动清理策略：retention_days: 30
   • 启用数据压缩：compression: zstd

AgentSociety模拟运行界面 - 展示城市地图上的智能体分布与实时交互状态

常见问题排查

问题1：LLM API调用失败

症状：模拟运行中出现APIConnectionError或TimeoutError

可能原因：

• API密钥无效或权限不足
• 网络连接问题或API服务中断
• 并发请求超过API配额限制

解决方案：

1. 验证API密钥有效性：

   agentsociety check -c my_config.yaml --llm-only
   

2. 调整并发控制参数：

   llm:
     - semaphore: 50  # 降低并发数
       timeout: 30  # 延长超时时间
   

3. 配置多LLM提供商容灾：

   llm:
     - provider: "openai"
       priority: 1  # 主用
     - provider: "qwen"
       priority: 2  # 备用
   

问题2：WebUI访问缓慢

症状：界面加载延迟，地图渲染卡顿

可能原因：

• 服务器资源不足
• 地图数据过大
• 浏览器缓存问题

解决方案：

1. 优化服务器配置：增加内存至32GB以上
2. 简化地图数据：

   # 简化地图文件（保留关键地理特征）
   agentsociety map simplify -i city.geojson -o city_simple.geojson -r 0.001
   

3. 浏览器端优化：
   • 清除缓存并强制刷新（Ctrl+Shift+R）
   • 关闭不必要的浏览器扩展

问题3：模拟运行中断

症状：模拟过程中突然停止，无错误提示

可能原因：

• 内存溢出（OOM）
• 智能体行为逻辑错误
• 数据库连接中断

解决方案：

1. 检查系统日志：

   tail -n 100 agentsociety_data/logs/main.log
   

2. 降低模拟规模：减少智能体数量或缩短模拟时长
3. 启用增量保存：

   exp:
     save_interval: 30  # 每30分钟保存一次状态
   

总结与进阶路径

通过本指南，你已掌握AgentSociety从环境准备到场景落地的完整部署流程。建议进阶学习路径：

1. 核心功能探索：深入了解智能体记忆机制与决策流程，参考packages/agentsociety/agentsociety/agent/源码
2. 自定义智能体开发：基于examples/prospect_theory/模板创建具有特定行为模式的智能体
3. 高级场景设计：结合docs/02-development-guide/文档设计复杂社会实验

AgentSociety作为开源项目持续迭代，建议定期通过git pull更新源码，并关注CHANGELOG.md了解最新功能与改进。