- [2025-6-27] π’ Our documentation is now available at YuLan-OneSim Docs, and the Docker image can be accessed at Docker Hub.
- [2025-5-13] π Initial release of YuLan-OneSim! Our paper is now available on arXiv.
YuLan-OneSim (ηε °-δΈθ±‘) is a groundbreaking social simulator that leverages Large Language Model (LLM) agents to model human social behaviors. Our framework bridges the gap between social science and artificial intelligence by offering a powerful, intuitive platform for research and exploration.
-
π Code-free scenario construction: Design complex simulations through natural language conversations
-
π Comprehensive default scenarios: 50+ default scenarios across 8 major social science domains
-
π§ Evolvable simulation: Models that automatically improve based on external feedback
-
π Large-scale simulation: Distributed architecture supporting up to 100,000 agents
-
π AI social researcher: Autonomous research from topic proposal to report generation
πΊ Watch Demo Video:
δΈζη |
English Version
You can install YuLan-OneSim either using Docker (recommended for quick setup) or from source for development.
We provide a Docker image for easy deployment and a Makefile to simplify common commands.
Prerequisites:
- Docker installed on your system.
Steps:
-
Clone the repository:
git clone https://github.com/RUC-GSAI/YuLan-OneSim cd YuLan-OneSim -
Configure your settings: Before starting, make sure to set up your API keys and other settings in
config/config.jsonandconfig/model_config.json. Refer to the Configuration section for details. -
Run with Makefile (Easiest): The
Makefileprovides simple commands to manage the container.make run
Once running, access the application:
- Web UI: http://localhost:8000
Other useful
makecommands:make build: Build the Docker image.make run: Start the container.make stop: Stop and remove the container.make logs: Follow container logs.make shell: Enter the container's shell.make clean: Stop the container and remove the image.
-
Run with Docker Commands: If you prefer not to use
make, you can usedockercommands directly.# Pull the pre-built image from Docker Hub docker pull ptss/yulan-onesim:latest # Or build it from source # docker build -t ptss/yulan-onesim:latest . # Run the container docker run -d --name yulan-onesim -p 8000:80 -v ./config:/app/config ptss/yulan-onesim:latest
# Clone the repository (if you haven't already)
git clone https://github.com/RUC-GSAI/YuLan-OneSim
cd YuLan-OneSim
# Install in editable mode
pip install -e .
# Install with tuning dependencies if needed
pip install -e .[tune]# Run a simulation with default settings
yulan-onesim-cli --config config/config.json --model_config config/model_config.json --mode single --env labor_market_matching_process# Start the backend API service (from the project root directory)
yulan-onesim-server
# In a new terminal, navigate to the frontend directory and start the frontend application
cd src/frontend
npm install # If you haven't installed dependencies
npm run dev # Or your specific command to start the frontendAccess the web interface (frontend) at http://localhost:5173 and the API documentation (backend) at http://localhost:8000/docs .
YuLan-OneSim uses JSON configuration files to control simulation behavior and model settings.
The frontend uses environment variables for configuration. Edit the following files in the src/frontend directory:
.env.development
# Development API endpoint (local development)
VITE_API_BASE_URL=http://localhost:8000
.env.production
# Production API endpoint (replace with your actual production server)
VITE_API_BASE_URL=https://your-production-server.com
These settings determine where the frontend will send API requests based on the environment. The VITE_API_BASE_URL variable is essential for connecting the frontend to the correct backend endpoint.
The simulation configuration file controls general simulation parameters:
{
"simulator": {
"environment": {
"name": "labor_market_matching_process", // Environment scenario to simulate
"mode": "round", // Simulation execution mode
"max_steps": 3, // Maximum simulation steps
"interval": 60.0, // Interval between simulation steps
"export_training_data": false, // Whether to export training data
"export_event_data": false // Whether to export event data
}
},
"agent": {
"planning": "COTPlanning", // Agent planning algorithm
"memory": {
"strategy": "ShortLongStrategy", // Memory management strategy
"storages": {
"short_term_storage": {
"class": "ListMemoryStorage", // Short-term memory storage type
"capacity": 100 // Maximum memory capacity
},
"long_term_storage": {
"class": "VectorMemoryStorage", // Long-term memory storage type
"capacity": 100,
"model_config_name": "openai_embedding-bert" // Embedding model for memory
}
},
"metric_weights": {
"recency": 0.7 // Weight for recency in memory retrieval
}
}
},
"database": {
"enabled": false, // Enable/disable database
"host": "localhost", // Database host
"port": 5432, // Database port
"dbname": "onesim" // Database name
},
"distribution": {
"enabled": false, // Enable/disable distributed mode
"mode": "single", // Running mode: single/distributed
"node_id": "1" // Node identifier for distributed mode
},
"monitor": {
"enabled": true, // Enable/disable monitoring
"update_interval": 30 // Monitor update interval
}
}Note: The model_config_name values under agent.memory (e.g., for long_term_storage and the relevance metric) must match the config_name of an embedding model defined in config/model_config.json.
Specifies the LLMs and embedding models used by the simulator:
{
"chat": [
{
"provider": "openai", // LLM provider: OpenAI
"config_name": "openai-gpt4o", // Configuration identifier
"model_name": "gpt-4o", // Model name
"api_key": "sk-xxx", // API key
"generate_args": {
"temperature": 0 // Temperature setting (0 = deterministic)
}
},
{
"provider": "vllm", // LLM provider: vLLM for local deployment
"config_name": "vllm-qwen", // Configuration identifier
"model_name": "Qwen2.5-14B-Instruct", // Model name or path
"client_args": {
"base_url": "http://localhost:9889/v1/" // Local API endpoint
},
"generate_args": {
"temperature": 0 // Temperature setting
}
}
],
"embedding": [
{
"provider": "vllm", // Embedding model type
"config_name": "vllm_embedding-bert", // Configuration identifier
"model_name": "bge-base-en-v1.5", // Embedding model name or path
"client_args": {
"base_url": "http://localhost:9890/v1/" // Local API endpoint
}
}
]
}YuLan-OneSim supports both cloud-based APIs (like OpenAI) and locally deployed models through vLLM, giving users flexibility in their model choices.
βββ config/ # Configuration files
βββ src/ # Main source code
β βββ onesim/ # Core simulation framework
β βββ backend/ # FastAPI backend
β βββ frontend/ # UI components
β βββ llm_tuning/# Model fine-tuning
β βββ envs/ # Simulation environments
β βββ researcher/# AI Social Researcher
βββ scripts/ # Utility scripts
1οΈβ£ Evaluation of the Automatic Scenario Generation Framework:
We conducted a comprehensive evaluation of YuLan-OneSim's capabilities in automatic scenario generation. In terms of efficiency, the simulator achieves an average generation speed of 358 tokens per second. In terms of effectiveness, the quality scores for the generated agent behavior graphs and code both exceed 4 points (based on the scoring criteria described in the paper), demonstrating the system's strong potential in automatic scenario construction.
Meanwhile, we observed that most of the errors generated by YuLan-OneSim are logical in nature. These include issues such as value access errors, mismatches between instructions and actions, incorrect value assignments, and omissions in type checking. Such errors can typically be resolved using standard debugging techniques and require minimal human intervention. However, their prevalence suggests that targeted improvements in logical verification could significantly enhance the reliability of the overall code generation process. Additionally, although syntax errors and robustness issues are also present in the generated outputs, they account for only a small portion of the total errors. While the current results are promising, our implementation still faces certain limitations when dealing with more complex logical dependencies and edge cases. To address these challenges, we plan to incorporate more advanced error detection and correction mechanisms in future work, aiming to further reduce the need for manual code adjustments.
2οΈβ£ Simulation Effectiveness Evaluation
To evaluate credibility, we conduct experiments from two perspectives: (1) Social Theory Validation β examining whether established classic social science theories can be validated within our simulation environment; (2) Real-World Data Alignment β assessing the degree of consistency between simulation results and real-world observational data.
In Experiment (1), we conduct simulations based on the Axelrod cultural dissemination model. As the simulation progresses, distinct cultural boundaries gradually emerge. Within each cultural region, neighboring agents exhibit high similarity (indicated by darker connection colors), while the boundaries between regions become increasingly clear. This visualization effectively reflects the core insight of Axelrod's theory: local interactions foster cultural homogeneity within regions, while cultural diversity is preserved on a global scale.
We also conducted a dynamic and quantitative analysis of the formation process underlying Axelrod's theory. As shown in the figure above, during the initial phase, the local convergence within communities gradually increases, while global polarization continues to declineβindicating that agents begin interacting and forming early-stage cultural clusters. Around the 15th iteration, an inflection point emerges: local convergence continues to rise, while global polarization stabilizes. This trend suggests that regions are becoming increasingly homogeneous internally, while the boundaries between different cultural groups remain clearly distinguishable.
These experimental results clearly illustrate the core of Axelrod's theoryβthe coexistence of local convergence and global polarization. YuLan-OneSim not only successfully reproduces this theoretical expectation but also provides a quantitative characterization of the process, offering deeper insights into the temporal dynamics of cultural dissemination.
In Experiment (2), we examine whether the data generated by the simulator aligns with real-world observations. Specifically, we conduct an experiment using housing market data from Brazil. Figure 8 presents a comparison between the simulated housing price distribution and the actual distribution in Brazil. The simulation successfully reproduces several key features observed in the real dataβmost notably, the multimodal distribution pattern with primary and secondary peaks that closely match the normalized values of the real distribution.
In the low-price range (0.05β0.25), the strong agreement between simulated and real data suggests that our model effectively captures the core dynamics of the most common housing market segment. Additionally, the simulation reflects the characteristic long-tail distribution often seen in housing markets. However, in the mid-range price interval (0.45β0.55), the simulation slightly underestimates the actual data. We attribute this discrepancy primarily to simplified modeling of the housing price formation process, which does not fully account for complex factors such as neighborhood livability, infrastructure quality, and historical valuations.
Despite this deviation, the overall results demonstrate that YuLan-OneSim can approximate real-world economic distribution patterns with high accuracy, validating its potential and practicality for applications in social science research.
3οΈβ£ Evaluation of the AI Social Researcher
In the evaluation of the AI Social Researcher, we focus primarily on the quality of the generated simulation scenario (ODD protocol) and the final analytical report. The results show that the AI Social Researcher performs well across all evaluation criteria for scenario design, achieving an average overall score of 4.13 out of 5. Notably, it excels in the "Feasibility" dimension, with an average score of 4.88, indicating its strong ability to translate abstract research questions into executable simulation plans. It also performs well in "Relevance" (average score of 4.25), ensuring that the generated scenarios are closely aligned with the user-defined research topics.
In terms of report generation, the AI Social Researcher demonstrates solid performance in "Structural Organization" (average score of 4.00) and "Content Completeness and Accuracy" (average score of 3.63), showing that it can effectively structure analysis results into logically coherent and well-supported technical reports. The top-performing reports include "Auction Market Dynamics" (Economics) and "Court Trial Simulation" (Law), each receiving an overall score of 4.0.
However, there remains room for improvement, particularly in the dimensions of "Insightfulness" (3.25) and "Practicality" (3.00). While the AI Social Researcher is competent in data analysis and reporting, it still struggles to extract deeper research insights and formulate actionable recommendations from simulation results. For instance, in the scenario "Labor Market Matching Process," the report received a low practicality score of 2.0, highlighting the current limitations of the model in certain domain-specific applications.
Contributions are welcome! Please feel free to submit a Pull Request.
If you use YuLan-OneSim in your research, please cite our paper:
@misc{wang2025yulanonesimgenerationsocialsimulator,
title={YuLan-OneSim: Towards the Next Generation of Social Simulator with Large Language Models},
author={Lei Wang and Heyang Gao and Xiaohe Bo and Xu Chen and Ji-Rong Wen},
year={2025},
eprint={2505.07581},
archivePrefix={arXiv},
primaryClass={cs.AI},
url={https://arxiv.org/abs/2505.07581},
}We would like to express our sincere gratitude to the AgentScope team from Alibaba Tongyi Lab , whose outstanding work has made this project possible. Their contributions have provided a solid foundation and essential tools that greatly enhanced the development process.
Special thanks to @pan-x-c (Xuchen Pan) and @glendon84 (Yaliang Li) for their invaluable guidance and support throughout the development of YuLan-OneSim.
This project is licensed under the Apache-2.0 License.
