AgentSociety 社会模拟平台安装与配置全指南

AgentSociety是一个基于大语言模型的大规模社会模拟平台，通过LLM驱动的智能体模拟人类行为与社会现象。本文将从核心价值出发，提供从环境准备到深度配置的完整流程，帮助用户快速构建社会模拟实验环境。

核心价值与应用场景

AgentSociety通过构建由AI驱动的智能体社会，实现对复杂社会现象的模拟与分析。其核心价值体现在：

• 微观行为建模：通过LLM驱动的智能体模拟个体决策过程
• 宏观涌现分析：观察群体行为如何从个体互动中涌现
• 政策实验平台：在虚拟环境中测试政策效果与社会响应
• 突发事件模拟：预测自然灾害、公共卫生事件等对社会的影响

AgentSociety架构概览 - 展示核心模块与应用场景的关系

环境准备

硬件加速方案

为确保模拟效率，建议根据实验规模选择以下硬件配置：

实验规模	CPU核心	内存要求	存储需求	加速建议
小型演示	4核	16GB	20GB	无特殊要求
中型实验	8核	32GB	50GB	启用GPU加速
大型模拟	16核+	64GB+	100GB+	多GPU分布式部署

⚠️ 注意：对于超过1000智能体的大规模模拟，建议使用具备AVX2指令集的CPU以提高并行计算效率。

软件依赖清单

基础依赖：

• Python 3.11+（推荐3.11.4版本）
• Python虚拟环境管理工具（venv/pipenv/conda）
• Git 2.30+（用于源码安装）
• SQLite 3.36+（默认数据库）

系统支持：

• Linux X86_64（推荐Ubuntu 22.04/Debian 11）
• MacOS ARM（M1/M2芯片）
• Windows用户需通过WSL 2运行

快速启动

安装方式选择

1. PyPI快速安装（推荐）：

# 创建并激活虚拟环境
python -m venv agentsociety-env
source agentsociety-env/bin/activate  # Linux/MacOS
# 安装核心包
pip install agentsociety
# 安装社区扩展和基准测试工具（可选）
pip install agentsociety-community agentsociety-benchmark

📋 复制代码

2. 源码安装（开发用途）：

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/ag/agentsociety
cd agentsociety
# 安装依赖管理工具
pip install uv
# 安装项目
uv pip install -e .

📋 复制代码

验证安装

安装完成后，执行以下命令验证：

agentsociety --version

成功安装会显示版本信息，例如：agentsociety 0.1.0

启动WebUI

创建基础配置文件ui_config.yaml：

addr: 0.0.0.0:8080
env:
  db:
    enabled: true
    db_type: sqlite
  home_dir: ./agentsociety_data

📋 复制代码

启动WebUI：

agentsociety ui -c ui_config.yaml

访问http://localhost:8080即可进入Web管理界面。

深度配置

基础配置

LLM配置（核心）： 创建llm_config.yaml文件：

llm:
- api_key: "your_api_key_here"
  base_url: "https://api.openai.com/v1"
  model: "gpt-4o"
  provider: "openai"
  semaphore: 200  # 并发控制
  timeout: 60     # 超时设置（秒）

📋 复制代码

LLM API配置界面 - 支持多提供商和模型选择

地图配置：

map:
  file_path: "./maps/city_map.geojson"
  resolution: 100  # 地图精度
  update_frequency: 300  # 更新频率（秒）

📋 复制代码

进阶优化

性能调优参数对照表：

参数	默认值	优化建议	适用场景
semaphore	100	200-500	高并发场景
batch_size	10	20-50	GPU加速环境
cache_ttl	3600	1800	动态环境
max_retries	3	5	不稳定网络
timeout	30	60-120	复杂推理任务

多LLM负载均衡配置：

llm:
- api_key: "key1"
  model: "gpt-4o"
  provider: "openai"
  semaphore: 150
  weight: 0.6  # 负载权重
- api_key: "key2"
  model: "qwen-max"
  provider: "qwen"
  semaphore: 200
  weight: 0.4

📋 复制代码

安全最佳实践

API密钥管理：

1. 使用环境变量存储密钥：

export AGENT_LLM_API_KEY="your_key_here"

📋 复制代码

2. 在配置文件中引用环境变量：

llm:
- api_key: "${AGENT_LLM_API_KEY}"
  # 其他配置...

📋 复制代码

⚠️ 注意：永远不要将API密钥直接提交到代码仓库或分享给他人。

数据安全配置：

env:
  db:
    enabled: true
    db_type: postgresql
    host: "db.internal"
    port: 5432
    username: "${DB_USER}"
    password: "${DB_PASSWORD}"
    ssl_mode: "require"

📋 复制代码

场景实践

场景一：小型社会网络模拟（100智能体）

配置文件small_simulation.yaml：

llm:
- api_key: "${OPENAI_API_KEY}"
  model: "gpt-3.5-turbo"
  provider: "openai"
  semaphore: 100
env:
  db:
    enabled: true
map:
  file_path: "./maps/small_town.geojson"
agents:
  citizens:
  - agent_class: "basic_citizen"
    number: 100
    profile_path: "./profiles/basic_profiles.json"
exp:
  name: "small_town_simulation"
  duration: 72  # 模拟时长（小时）
  tick_interval: 300  # 模拟步长（秒）

📋 复制代码

启动命令：

agentsociety run -c small_simulation.yaml

📋 复制代码

场景二：政策影响分析（500智能体）

配置文件policy_analysis.yaml：

llm:
- api_key: "${DEEPSEEK_API_KEY}"
  model: "deepseek-chat"
  provider: "deepseek"
  semaphore: 200
agents:
  citizens:
  - agent_class: "policy_aware_citizen"
    number: 500
    profile_path: "./profiles/policy_profiles.json"
  government:
  - agent_class: "government_agent"
    number: 5
exp:
  name: "ubi_policy_analysis"
  environment:
    start_tick: 28800
  workflow:
  - day: 1-30
    type: "baseline"
  - day: 31-60
    type: "policy_implementation"
    policy: "ubi"
    parameters:
      amount: 1000
      frequency: "monthly"
  - day: 61-90
    type: "impact_analysis"

📋 复制代码

场景三：灾难响应模拟（1000+智能体）

此场景建议使用分布式部署，配置文件disaster_simulation.yaml：

llm:
- api_key: "${QWEN_API_KEY}"
  model: "qwen-max"
  provider: "qwen"
  semaphore: 500
- api_key: "${ZHIPU_API_KEY}"
  model: "glm-4"
  provider: "zhipuai"
  semaphore: 500
env:
  distributed: true
  workers: 8
  db:
    enabled: true
    db_type: "postgresql"
map:
  file_path: "./maps/metropolitan_area.geojson"
agents:
  citizens:
  - agent_class: "disaster_aware_citizen"
    number: 1500
  emergency:
  - agent_class: "emergency_responder"
    number: 50
exp:
  name: "hurricane_response_simulation"
  disaster:
    type: "hurricane"
    start_day: 15
    severity: "major"

📋 复制代码

AgentSociety模拟运行界面 - 展示智能体在地图上的分布与交互

问题解决

常见错误与解决方案

1. LLM API调用失败

• 检查API密钥有效性和余额
• 验证网络连接和代理设置
• 调整timeout参数（建议60-120秒）
• 启用多LLM配置实现故障转移

2. WebUI访问问题

• 检查端口占用情况：netstat -tulpn | grep 8080
• 确认防火墙设置：ufw allow 8080/tcp
• 尝试绑定所有网络接口：addr: 0.0.0.0:8080

3. 模拟性能问题

• 减少semaphore值降低并发压力
• 增加tick_interval减少模拟频率
• 启用数据库连接池：db.pool_size: 20
• 考虑使用Redis缓存频繁访问的数据

多环境部署对比

部署方式	优势	劣势	适用场景
本地部署	配置简单，低延迟	资源受限，难以扩展	开发测试，小型实验
Docker容器	环境一致，部署便捷	性能开销，资源隔离	团队协作，标准化部署
云服务	弹性扩展，高可用性	成本较高，网络依赖	大规模模拟，长期运行

Docker部署示例：

# 构建镜像
docker build -t agentsociety:latest .
# 运行容器
docker run -d -p 8080:8080 -v ./data:/app/data agentsociety:latest

📋 复制代码

通过本文指南，您已掌握AgentSociety的安装配置全过程。根据实验需求选择合适的配置方案，开始探索复杂社会系统的运行机制与规律。对于大规模部署，建议参考官方文档中的分布式部署指南以获得最佳性能。