6步构建LLM驱动的社会模拟平台：AgentSociety智能体系统安装与多智能体配置指南

AgentSociety是一个基于大语言模型（LLM）的大规模社会模拟平台，通过LLM驱动的智能体来理解和模拟人类行为与社会现象。本指南将帮助你从零开始搭建这一强大工具，实现群体行为模拟与复杂社会系统分析。

1. 核心功能概览：AgentSociety能做什么

AgentSociety作为新一代社会模拟平台，核心价值在于通过AI驱动的智能体（可以理解为"数字人"）模拟真实社会中的个体行为与群体互动。其核心功能包括：

• 多智能体系统：支持数百至数千个独立决策的AI智能体，每个智能体拥有独特的背景、性格和行为模式
• 社会环境建模：构建包含地理空间、经济系统、社会关系网络的完整模拟环境
• 复杂场景模拟：可模拟疫情传播、舆论演化、政策影响等多种社会现象
• 实时可视化：通过Web界面直观观察智能体行为和社会动态变化

AgentSociety架构概览 - 展示核心模块的层次结构和关联关系，包括社会环境、智能体系统和大规模交互等关键组件

经验速记：AgentSociety的优势在于将LLM的推理能力与社会科学模型结合，适合社会学、经济学、公共政策等领域的模拟研究。

2. 环境校验：你的系统准备好了吗

在开始安装前，需要确保系统满足以下要求，避免后续出现兼容性问题。

硬件配置要求

• 基础配置（个人学习）：4核CPU，16GB内存，10GB存储空间
• 推荐配置（小规模模拟）：8核CPU，32GB内存，50GB SSD存储
• 极限配置（大规模实验）：16核CPU，64GB内存，100GB SSD，GPU加速（推荐NVIDIA RTX 3090及以上）

软件环境兼容性矩阵

软件/工具	最低版本	推荐版本	不兼容版本
Python	3.11	3.11.4	<3.10, 3.12+
pip	22.0	23.3.1	<21.0
Node.js	16.0	18.18.0	<14.0
Docker	20.10	24.0.6	<19.0
操作系统	Linux x86_64/MacOS ARM	Ubuntu 22.04/MacOS 13	Windows（需WSL2）

🔍 检查点：在终端输入以下命令验证Python版本：

python --version  # 应返回3.11.x

经验速记：使用pyenv或conda管理Python环境可避免版本冲突，推荐创建独立虚拟环境进行安装。

3. 分步部署：从安装到启动的完整流程

按照以下步骤，你将在几分钟内完成AgentSociety的基础部署。

步骤1：获取源代码

git clone https://gitcode.com/gh_mirrors/ag/agentsociety
cd agentsociety

步骤2：安装核心组件

# 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/MacOS
# 或在Windows WSL中使用: . venv/bin/activate

# 安装核心包
pip install .

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

🔍 检查点：验证安装是否成功：

agentsociety --version

若成功安装，将显示版本号信息。

步骤3：启动WebUI

# 创建UI配置文件
cat > ui.yaml << EOF
addr: 127.0.0.1:8080
env:
  db:
    enabled: true
    db_type: sqlite
  home_dir: ./agentsociety_data
EOF

# 启动Web界面
agentsociety ui -c ./ui.yaml

启动成功后，访问 http://127.0.0.1:8080 即可打开AgentSociety的Web管理界面。

经验速记：首次启动会自动创建数据库和必要目录结构，建议将数据目录备份或设置到非系统盘。

4. 场景化配置：三种环境下的最佳实践

根据你的使用场景，选择以下配置方案之一进行系统设置。

本地部署配置（个人学习）

适合个人电脑或笔记本环境，使用SQLite数据库和本地文件存储：

# 本地开发配置示例
llm:
- api_key: your_api_key_here  # 替换为你的LLM API密钥
  base_url: https://api.openai.com/v1  # 根据实际使用的LLM提供商修改
  model: gpt-4o  # 或其他可用模型
  provider: openai  # 模型提供商
  semaphore: 50  # 并发请求限制（本地环境建议50以下）
env:
  db:
    enabled: true
    db_type: sqlite
  home_dir: ~/agentsociety_data  # 本地数据存储路径
map:
  file_path: ./examples/map/sample_map.geojson  # 示例地图文件
agents:
  citizens:
  - agent_class: citizen
    number: 50  # 本地环境建议从少量智能体开始
exp:
  name: local_demo_experiment
  environment:
    start_tick: 28800
  workflow:
  - day: 1
    type: run

云服务器配置（团队协作）

适合云服务器环境，支持多用户访问和更大规模模拟：

# 云服务器配置示例
llm:
- api_key: team_api_key_1
  model: gpt-4o
  provider: openai
  semaphore: 200  # 云服务器可适当提高并发限制
- api_key: team_api_key_2  # 配置多个API密钥实现负载均衡
  model: qwen-max
  provider: qwen
  semaphore: 200
env:
  db:
    enabled: true
    db_type: postgresql  # 使用PostgreSQL支持多用户访问
    host: localhost
    port: 5432
    username: agentsociety
    password: secure_password_here
    database: agentsociety_db
  home_dir: /var/lib/agentsociety_data
map:
  file_path: /opt/agentsociety/maps/city_map.geojson
agents:
  citizens:
  - agent_class: citizen
    number: 500  # 云服务器可支持更多智能体
exp:
  name: cloud_experiment
  environment:
    start_tick: 28800
  workflow:
  - day: 7  # 更长的模拟周期
    type: run

容器化部署（生产环境）

使用Docker容器化部署，便于环境一致性和快速扩展：

# 构建Docker镜像
./scripts/build_docker.sh

# 启动容器
docker run -d -p 8080:8080 \
  -v ./agentsociety_data:/app/data \
  -e LLM_API_KEY=your_api_key \
  -e LLM_PROVIDER=openai \
  --name agentsociety \
  agentsociety:latest

LLM API配置界面 - 支持多种提供商和模型选择，可配置多个API密钥实现负载均衡

经验速记：容器化部署时，建议将数据目录和配置文件挂载到宿主机，避免容器重启导致数据丢失。

5. 问题诊断：常见故障的四步排查法

遇到问题时，按照"症状-可能原因-验证方法-解决方案"四步法进行排查：

问题1：WebUI启动后无法访问

• 症状：浏览器访问http://127.0.0.1:8080无响应
• 可能原因：端口被占用、防火墙限制、配置文件错误
• 验证方法：

  # 检查端口占用情况
  netstat -tuln | grep 8080
  # 查看应用日志
  cat agentsociety_data/logs/app.log
  

• 解决方案：
  • 更换端口：修改ui.yaml中的addr为127.0.0.1:8081
  • 开放防火墙：sudo ufw allow 8080
  • 检查配置文件格式：使用yamllint验证配置文件

问题2：LLM API调用失败

• 症状：模拟运行时智能体无响应，日志显示API错误
• 可能原因：API密钥错误、网络连接问题、并发过高
• 验证方法：

  # 检查API密钥有效性
  curl -X POST https://api.openai.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer your_api_key" \
    -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"Hello"}]}'
  

• 解决方案：
  • 验证API密钥和权限
  • 降低semaphore值减少并发请求
  • 配置多个LLM提供商实现故障转移

问题3：模拟运行缓慢

• 症状：模拟进度停滞或运行速度远低于预期
• 可能原因：硬件资源不足、智能体数量过多、LLM响应慢
• 验证方法：

  # 检查系统资源使用情况
  top  # 查看CPU和内存占用
  

• 解决方案：
  • 增加硬件资源或优化配置
  • 减少同时运行的智能体数量
  • 使用更高性能的LLM模型或服务

经验速记：启用详细日志记录（在配置文件中设置log_level: DEBUG）有助于快速定位问题根源。

6. 高级调优：从可用到高效的性能提升

通过以下调优策略，可以显著提升AgentSociety的运行效率和模拟质量。

LLM配置优化

多LLM组合配置可大幅提升系统稳定性和响应速度：

llm:
- api_key: key1
  model: gpt-4o
  provider: openai
  semaphore: 100  # 每个API的并发限制
  weight: 0.6     # 权重分配
- api_key: key2
  model: qwen-max
  provider: qwen
  semaphore: 100
  weight: 0.4
- api_key: key3
  model: deepseek-chat
  provider: deepseek
  semaphore: 50
  weight: 0.2
  fallback: true  # 作为备用LLM

性能测试指标与优化效果

配置方案	智能体数量	平均响应时间	每小时模拟步数	资源占用
默认配置	100	2.3秒	120	CPU: 60%, 内存: 4GB
多LLM配置	200	1.8秒	210	CPU: 75%, 内存: 6GB
优化后配置	300	1.5秒	320	CPU: 80%, 内存: 8GB

移动端适配说明

AgentSociety WebUI支持移动端访问，通过以下配置优化移动体验：

# 在ui.yaml中添加
web:
  responsive: true
  mobile:
    enabled: true
    simplified_mode: true  # 启用简化界面
    max_agents_display: 50  # 移动端限制显示智能体数量

AgentSociety模拟运行效果 - 展示智能体在地图上的分布和实时交互情况

经验速记：对于大规模模拟（500+智能体），建议使用专用服务器并启用分布式计算模式，可通过agentsociety run --distributed命令启动。

通过本指南，你已经掌握了AgentSociety从安装到高级配置的全过程。无论是学术研究、政策模拟还是教育演示，AgentSociety都能为你提供强大的社会模拟能力。开始你的第一个社会模拟实验，探索复杂系统背后的规律吧！