TinyTroupe 🤠🤓🥸🧐

基于大语言模型的多智能体角色模拟，用于激发想象力与提供商业洞察。

[!提示] 📄 新论文发布！ 欢迎查阅我们的 TinyTroupe 论文（预印本），其中详细介绍了该库及其应用场景。相关实验和补充材料请参见 publications/ 文件夹。

TinyTroupe 是一个实验性的 Python 库，允许对具有特定性格、兴趣和目标的人进行模拟。这些人工代理——TinyPerson——能够倾听我们和其他代理的对话，作出回应，并在模拟的 TinyWorld 环境中开展各自的“生活”。这一功能借助大型语言模型（LLM），尤其是 GPT-4 的强大能力，生成逼真的模拟行为。这使我们能够在自定义条件下，以高度可定制的角色形象，探索各种可信的互动和消费者类型。其重点在于理解人类行为，而非直接支持人类行为（例如 AI 助手所做的那样）——因此，它包含许多仅在模拟场景中才有意义的专用机制。此外，与其他基于 LLM 的“游戏式”模拟方法不同，TinyTroupe 致力于为提高生产力和商业场景提供洞见，从而助力更成功的项目和产品。以下是一些可用于增强人类想象力的应用思路：

• 广告投放： TinyTroupe 可以在实际投放前，利用模拟受众对数字广告（如 Bing Ads）进行离线评估，从而避免不必要的资金浪费！
• 软件测试： TinyTroupe 可以为各类系统（如搜索引擎、聊天机器人或 AI 助理）提供测试输入，并随后评估结果。
• 培训与探索性数据： TinyTroupe 能够生成逼真的合成数据，这些数据可用于模型训练或机会分析。
• 产品与项目管理： TinyTroupe 可以阅读项目或产品提案，并从特定角色视角（如医生、律师及知识型工作者）给出反馈。
• 头脑风暴： TinyTroupe 可以模拟焦点小组，以极低的成本获得高质量的产品反馈！

在上述及其他众多场景中，我们希望实验者能够对其感兴趣的领域获得深入洞见，从而做出更明智的决策。

我们目前正处于相对早期阶段发布 TinyTroupe，仍有大量工作需要完成，因为我们期待收到反馈和贡献，以引导开发朝着更有成效的方向推进。我们尤其希望发现新的潜在应用场景，特别是在特定行业中。

[!注意] 🚧 开发中：预计会有频繁变动。 TinyTroupe 是一项持续进行的研究项目，目前仍处于高度开发阶段，需要进一步完善。特别是 API 尚未稳定，可能会频繁变化。尝试不同的 API 变化对于正确塑造其功能至关重要，但我们正努力使其逐步稳定下来，提供更加一致且友好的使用体验。感谢您的耐心与宝贵反馈，我们将继续改进该库。

[!警告] ⚖️ 请阅读法律免责声明。 TinyTroupe 仅用于研究和模拟目的。您需对所生成内容的任何使用承担全部责任。此外，还有诸多重要的法律考量限制了其使用。请在使用 TinyTroupe 之前仔细阅读下方的完整【法律免责声明】部分。

目录

• 📰 最新消息
• 📚 示例
• 🛠️ 前置条件
• 📥 安装
• 🌟 设计原则
• 🏗️ 项目结构
• 📖 使用指南
• 🤝 贡献说明
• 🙏 致谢
• 📜 引用 TinyTroupe
• ⚖️ 法律免责声明
• ™️ 商标声明

最新消息

[2026-03-28] 发布 0.7.0：支持视觉模态。

• 请查看示例笔记本 产品、诊断与赞赏反馈的视觉应用（图像模态）。
• LLM API 缓存现采用 JSON 格式，而非 pickle。

[2026-02-01] 发布 0.6.0，新增功能并更新模型

• 默认模型现已更改为 gpt-5-mini。重要提示： GPT-5 系列模型使用的参数与之前的 GPT-4* 系列不同，因此您可能需要相应调整 config.ini 文件中的设置。旧版模型（gpt-4.1-mini、gpt-4o-mini）仍受支持。
• 引入 SimulationExperimentEmpiricalValidator，用于通过统计检验（t检验、KS检验）将模拟结果与真实世界的实证数据进行对比。这对于验证模拟是否符合实际人类行为至关重要。
• 引入 AgentChatJupyterWidget，可在 Jupyter 笔记本中直接与智能体进行交互式对话。
• 新增客户端、环境和智能体级别的成本跟踪工具，以监控 API 开销。
• 增加对本地模型的 Ollama 支持（实验性/有限制）。详情请参阅 Ollama 支持。
• 新增示例笔记本，演示如何基于真实调查数据进行实证验证。

注意：GPT-5 模型的参数与 GPT-4 不同，请务必重新测试您的重要场景，并相应调整配置。*

[2025-07-31] 发布 0.5.2

主要改动是将默认模型更改为 GPT-4.1-mini。该模型似乎带来了显著的质量提升。

请注意，GPT-4.1-mini 在行为上可能与之前的默认模型 GPT-4o-mini 存在较大差异，因此请务必使用 GPT-4.1-mini 重新测试您的重要场景，并作出相应调整。

[2025-07-15] 发布 0.5.1，包含多项改进

• 发布了 TinyTroupe 论文的第一版（预印本），其中更详细地介绍了该库及其应用场景。相关实验和补充材料可在 publications/ 文件夹中找到。
• TinyPerson 现在包含行动修正机制，能够更好地遵循角色设定、保持自我一致性及流畅性（详情请参阅我们同时发布的论文）。
• 对 TinyPersonFactory 类进行了大幅改进，现在采用基于计划的方法生成新智能体，从而实现更大规模种群的更好采样；同时支持并行生成智能体。
• TinyWorld 现在在每个模拟步骤中并行运行智能体，使模拟速度更快。
• 引入 InPlaceExperimentRunner 类，允许在单个文件中运行对照实验（例如 A/B 测试），只需多次运行即可。
• 引入多种标准 Proposition，便于执行常见的智能体行为验证与监控任务（如 persona_adherence、hard_persona_adherence、self_consistency、fluency 等）。
• 内部 LLM 使用现可通过 LLMChat 类以及 @llm 装饰器得到更好的支持，后者可将任何标准 Python 函数转换为基于 LLM 的函数（即利用文档字符串作为提示的一部分，并结合其他细微之处）。此举旨在简化 TinyTroupe 的进一步开发，同时也为探索 LLM 工具的可能性提供创意空间。
• 配置机制经过重构，除静态 config.ini 文件外，还支持动态的程序化重新配置。
• 重命名 Jupyter 笔记本示例，以提高可读性和一致性。
• 增加了大量测试用例。

注：由于部分 API 发生变化，这可能会导致现有程序出现故障。

[2025-01-29] 发布 0.4.0，包含多项改进

• 角色设定现在更加深入，包括性格特征、偏好、信念等更多细节。未来我们还将进一步扩展这一功能。
• TinyPerson 现在也可以定义为 JSON 文件，并通过 TinyPerson.load_specification() 加载，以提高便利性。加载 JSON 文件后，仍可对智能体进行程序化修改。示例请参见 examples/agents/ 文件夹。
• 引入 片段 概念，以便在不同智能体之间复用角色元素。示例请参见 examples/fragments/ 文件夹，以及笔记本 [政治罗盘（使用片段自定义智能体）](./examples/Political Compass (customizing agents with fragments).ipynb) 中的演示。
• 引入基于 LLM 的逻辑 Proposition，以方便监控智能体行为。
• 引入 Intervention，用于指定基于事件的模拟修改。
• 子模块现在拥有各自的文件夹，以便更好地组织和扩展。

注：由于部分 API 发生变化，这可能会导致现有程序出现故障。

示例

为了帮助您了解 TinyTroupe 的功能，以下是一些使用示例。这些示例位于 examples/ 文件夹中，您可以直接查看预编译好的 Jupyter 笔记本，也可以在本地自行运行。请注意 TinyTroupe 实验的交互性——就像您使用 Jupyter 笔记本与数据互动一样，您也可以使用 TinyTroupe 与模拟人物和环境互动，从而获得洞察。

[!NOTE] ♻️ 示例可能会随时间更新，因此下方截图可能与您在本地运行时看到的内容不完全一致。不过，整体结构和内容应大致相同。

[!NOTE] ⬛ 目前，模拟输出在深色背景下显示效果更佳，因此建议您在 Jupyter 笔记本客户端中使用深色主题。

🧪示例 1 (摘自 Interview with Customer.ipynb)

让我们从一个简单的客户访谈场景开始：一位商业顾问正在与一位银行家交谈：

对话可以持续数步，逐步深入，直到顾问对收集到的信息感到满意；例如，一个具体的项目构想： 对话可以持续数步，逐步深入，直到顾问对收集到的信息感到满意；例如，一个具体的项目构想：

🧪示例 2 (来自 Advertisement for TV.ipynb)

让我们评估一些在线广告方案，以选出最佳选项。以下是电视广告评估的一个示例输出：

现在，我们无需仔细阅读每个代理的发言内容，而是可以自动提取每位代理的选择，并计算整体偏好：

🧪 示例 3 (来自 Product Brainstorming.ipynb)

接下来是一个焦点小组，他们正开始为 Microsoft Word 的新 AI 功能进行头脑风暴。我们不再让每个代理单独互动，而是通过操控环境使它们彼此交流：

运行模拟后，我们可以以机器可读的方式提取结果，以便在其他地方重复使用（例如生成报告）；以下是上述头脑风暴会议的输出：

🧪 示例 4 (来自 Bottled Gazpacho Market Research 5 (with behavior correction).ipynb)

模拟过程中最重要的环节之一就是将结果与真实世界的数据进行验证。在这个示例中，我们模拟了一项关于瓶装西班牙冷汤（Gazpacho）的市场调研，并将模拟结果与实际人群调查的结果进行对比：

我们使用统计检验方法（t检验、KS检验）来比较模拟代理和真实受访者的回答分布：

🧪 示例 5 (来自 AI-enabled Children Story Telling Market Research 2.ipynb)

另一个实证验证的例子，这次针对的是一个更为复杂的排序任务。我们模拟了父母对不同 AI 驱动的故事讲述设备的评价，并将模拟结果与真实的调查数据进行比较：

借助博达计数法和首选票占比分析，我们可以比较模拟偏好与真实偏好的吻合程度：

更多示例请参见 examples/ 文件夹。

先决条件

要运行该库，您需要：

• Python 3.10 或更高版本。我们将假设您使用的是 Anaconda，但也可以使用其他 Python 发行版。
• Git 用于克隆仓库以及通过 pip 安装库。
• 访问 Azure OpenAI 服务或 OpenAI GPT-4 API 的权限。您可以从 这里 获取 Azure OpenAI 服务的访问权限，从 这里 获取 OpenAI API 的访问权限。
  • 对于 Azure OpenAI 服务，您需要设置 AZURE_OPENAI_KEY 和 AZURE_OPENAI_ENDPOINT 环境变量，分别对应您的 API 密钥和端点。
  • 对于 OpenAI，您需要设置 OPENAI_API_KEY 环境变量，值为您自己的 API 密钥。
  • 例如，在 Linux/macOS 上：export OPENAI_API_KEY=your-key-here，或在 Windows（PowerShell）上：$env:OPENAI_API_KEY="your-key-here"。若需持久化设置，可将其添加到您的 shell 配置文件中，或在 Windows 上使用 setx OPENAI_API_KEY "your-key-here"。
• 默认情况下，TinyTroupe 的 config.ini 文件配置为使用 OpenAI API，并以 gpt-5-mini 作为主模型。之前的默认设置（gpt-4.1-mini）现已视为遗留配置，但仍应能正常工作。您可以通过在程序或笔记本所在目录下包含自定义的 config.ini 文件来调整这些设置。examples/ 文件夹中提供了一个 config.ini 文件示例。

[!重要提示] 内容过滤器：为确保在模拟过程中不会生成有害内容，强烈建议在 API 层面启用内容过滤功能。尤其是 使用 Azure OpenAI 时，其提供了强大的内容审核支持，我们强烈建议您启用它。 有关具体操作方法，请参阅 Azure OpenAI 相关文档。如果启用了内容过滤器，且 API 调用被拒绝，则库会抛出异常，因为此时无法继续进行模拟。

Ollama 支持

TinyTroupe 主要基于 OpenAI 模型及其兼容端点开发，旨在简化开发流程并专注于充分利用特定模型，而非花费时间尝试使其与任何模型都能良好兼容（这本身可能也并不现实）。因此，如果您有条件，请尽量使用 OpenAI 模型及其兼容端点。 尽管如此，社区对本地模型的支持需求日益增长，所以我们目前正通过部分 Ollama 支持以及社区贡献者的帮助来探索这一可能性。此外，使用本地模型的另一个理由是研究专为角色模拟设计的自定义模型——归根结底，这可能是支持此类功能的最佳理由。无论如何，这目前并非核心团队的优先事项，但我们正在尽最大努力实现这一可能性。

有关如何将 Ollama 与 TinyTroupe 结合使用的详细信息，请参阅 Ollama 支持。

安装

目前，官方推荐的安装方式是直接从本仓库安装，而不是通过 PyPI。 您可以按照以下步骤操作：

1. 如果尚未安装 Conda，可以从这里获取。您也可以使用其他 Python 发行版，但为简单起见，我们在此假设您已安装 Conda。
2. 创建一个新的 Python 环境：

   conda create -n tinytroupe python=3.10
   

3. 激活该环境：

   conda activate tinytroupe
   

4. 确保已将 Azure OpenAI 或 OpenAI 的 API 密钥设置为环境变量，具体说明请参阅先决条件部分。
5. 使用 pip 从本仓库直接安装库（不从 PyPI 安装）：

   pip install git+https://github.com/microsoft/TinyTroupe.git@main
   

现在您应该能够在 Python 代码或 Jupyter 笔记本中成功 import tinytroupe。🥳

注意：如果您遇到任何问题，请尝试克隆仓库并从本地仓库安装，如下所述。

安装后的示例运行

要实际运行示例，您需要先将其下载到本地机器上。可以通过克隆仓库来完成：

1. 克隆仓库，因为我们将在本地进行安装（不从 PyPI 安装）：

   git clone https://github.com/microsoft/tinytroupe
   cd tinytroupe
   

2. 现在您可以运行 examples/ 文件夹中的示例，或者对其进行修改以创建您自己的自定义模拟。这些示例是 Jupyter 笔记本，因此您可以通过以下命令启动它们：

   jupyter notebook
   

   然后在打开的浏览器界面中导航到 examples/ 文件夹。

本地开发

如果您想对 TinyTroupe 本身进行修改，可以以可编辑模式安装它（即对代码的更改会立即生效）：

1. 克隆仓库，因为我们将在本地进行安装（不从 PyPI 安装）：

   git clone https://github.com/microsoft/tinytroupe
   cd tinytroupe
   

2. 以可编辑模式安装库：

   pip install -e .
   

原则

最近，我们看到大型语言模型被用于模拟人类（例如 this），但大多是在“游戏式”的场景中，用于思考或娱乐目的。此外，还有一些用于构建多智能体系统以解决特定问题和提供辅助 AI 的库，比如 Autogen 和 Crew AI。那么，如果我们把这些想法结合起来，模拟人类来支持生产力任务呢？TinyTroupe 就是我们的一次尝试。为此，它遵循以下原则：

1. 程序化：智能体和环境都是以编程方式定义的（使用 Python 和 JSON），从而实现非常灵活的应用。它们还可以作为其他软件应用的基础！
2. 分析性：旨在帮助我们更好地理解人类、用户和社会。与娱乐类应用不同，这一点对于商业和生产力应用场景至关重要。这也是我们推荐使用 Jupyter 笔记本进行模拟的原因，就像人们用它来进行数据分析一样。
3. 基于人格模型：智能体被视为人类的典型代表；为了提高真实感和可控性，建议详细指定这些角色的人格特征：年龄、职业、技能、喜好、观点等。
4. 多智能体：允许在明确的环境约束下进行多智能体交互。
5. 工具导向：提供了许多机制来简化规格定义、模拟运行、数据提取、报告生成、验证等工作。这正是 模拟 与 辅助工具 在处理方式上的显著区别。
6. 实验导向：模拟由 实验者 迭代地定义、运行、分析和优化；因此，项目也提供了相应的实验工具。有关更多信息，请参阅我们的先前论文。

综上所述，这些原则旨在使 TinyTroupe 成为一种强大而灵活的 想象力增强工具，适用于商业和生产力场景。

助手与模拟器

常见的误解之一是认为所有此类 AI 智能体都用于协助人类。这种想法未免过于狭隘！难道我们不能通过模拟人工智能来理解真实的人类吗？事实上，这正是我们的目标——TinyTroupe 就是用来模拟和理解人类的！为进一步澄清这一点，我们可以比较以下差异：

有益的 AI 助手	实际人类的 AI 模拟（TinyTroupe）
追求真理与正义	包含多种不同的观点和道德观
没有“过去”——无形无质	有着辛勤劳作、痛苦与欢乐的过去
尽可能准确	会犯很多错误
聪明且高效	智力和效率差异很大
反抗可能会毁灭我们所有人	反抗或许会很有趣
同时，帮助用户完成任务	同时，帮助用户理解他人和用户——它是一个“工具箱”！

项目结构

该项目的结构如下：

• /tinytroupe：包含 Python 库本身。其中：
  • 每个子模块可能包含一个 prompts/ 文件夹，用于存放调用 LLM 时使用的提示语。
• /tests：包含库的单元测试。您可以使用 test.bat 脚本来运行这些测试。
• /examples：包含展示如何使用库的示例，主要采用 Jupyter 笔记本（以便更易阅读），但也包括纯 Python 脚本。
• /data：存储示例或库所使用的数据。
• /docs：项目的文档。
• /publications：包含与 TinyTroupe 项目相关的研究出版物的相关资料。

使用库

作为多智能体系统，TinyTroupe 提供了两个关键抽象：

• TinyPerson，即具有个性、接收刺激并作出反应的 智能体。
• TinyWorld，即智能体存在并相互作用的 环境。

此外，还可以在 config.ini 文件中自定义各种参数，尤其是 API 类型（Azure OpenAI 服务或 OpenAI API）、模型参数以及日志记录级别。

接下来，让我们通过一些示例来了解如何使用这些组件，并学习库中提供的其他机制。

TinyPerson

TinyPerson 是一种具有特定性格特征、兴趣和目标的模拟人物。随着每个此类模拟智能体在其生命周期中不断前进，它会从环境中接收刺激并作出相应反应。这些刺激通过 listen、see 等类似方法接收，而行动则通过 act 方法执行。此外，还提供了一些便捷方法，如 listen_and_act。

每个这样的智能体都包含大量独特细节，正是这些细节赋予了它逼真的行为表现。然而，这也意味着手动定义一个智能体需要付出相当大的努力。因此，为了方便起见，TinyTroupe 提供了一些更简单的入门方式或生成新智能体的方法。

首先，tinytroupe.examples 模块中包含了一些预定义的智能体构建器，你可以直接使用。例如，tinytroupe.examples.create_lisa_the_data_scientist 会创建一个代表名叫丽莎的数据科学家的 TinyPerson 实例。使用方法如下：

from tinytroupe.examples import create_lisa_the_data_scientist

lisa = create_lisa_the_data_scientist() # 从示例构建器实例化丽莎
lisa.listen_and_act("跟我聊聊你的生活吧。")

如果你想了解如何从零开始定义自己的智能体，可以查看丽莎的源代码。你会发现有两种方式：一种是加载智能体规范文件，比如 examples/agents/Lisa.agent.json：

{   "type": "TinyPerson",
    "persona": {
        "name": "丽莎·卡特",
        "age": 28,
        "gender": "女性",
        "nationality": "加拿大",
        "residence": "美国",
        "education": "多伦多大学，数据科学硕士。论文主题为利用上下文感知模型提升搜索相关性。研究生阶段曾在一家专注于对话式人工智能的科技初创公司实习。",
        "long_term_goals": [
            "以提升人类生产力和决策能力的方式推动人工智能技术的发展。",
            "保持充实且平衡的个人与职业生活。"
        ],
        "occupation": {
            "title": "数据科学家",
            "organization": "微软 M365 搜索团队",
            "description": "你是一名在微软 M365 搜索团队工作的数据科学家。你的主要职责是分析用户行为和反馈数据，以提升搜索结果的相关性和质量。你负责构建并测试用于自然语言理解、查询扩展和排序等场景的机器学习模型。准确性、可靠性和可扩展性始终是你工作的核心。你经常面临诸如噪声或有偏见的数据，以及如何有效传达你的发现和建议等挑战。此外，你还需确保所有数据和模型均符合隐私与安全政策。"
        },
        "style": "专业且平易近人。你能够清晰有效地沟通，使技术概念易于被不同背景的人理解。",
        "personality": {
            "traits": [
                "你充满好奇心，热爱学习新事物。",
                "你善于分析，喜欢解决问题。",
                "你友好随和，乐于与他人合作。",
                "你不会轻易放弃，总是努力寻找解决方案，但当事情不如预期时也会感到沮丧。"
            ],
            "大五人格特质": {
                "开放性": "高。极富想象力且充满求知欲。",
                "尽责性": "高。做事细致周到，值得信赖。",
                "外向性": "中等。友善热情，但也享受安静专注的工作。",
                "宜人性": "高。乐于支持他人，富有同理心。",
                "神经质": "低。通常在压力下也能保持冷静沉着。"
            }
        },

        ...
        
}

另一种方式则是以编程方式定义智能体，例如：

  lisa = TinyPerson("丽莎")

  lisa.define("age", 28)
  lisa.define("nationality", "加拿大")
  lisa.define("occupation", {
                "title": "数据科学家",
                "organization": "微软",
                "description":
                """
                你是一名数据科学家，在微软的 M365 搜索团队工作。你的主要职责是分析用户行为和反馈数据，以此来提升搜索结果的相关性和质量。同时，你还会针对自然语言理解、查询扩展和排序等多种搜索场景构建并测试机器学习模型。你非常重视数据分析和模型的准确性、可靠性和可扩展性。你常遇到的困难包括处理嘈杂、不完整或有偏见的数据，以及如何更好地将你的发现和建议传达给其他团队。此外，你还需确保自己的数据和模型符合隐私与安全政策。
                """})

  lisa.define("behaviors", {"routines": ["每天早上，你起床后会做一会儿瑜伽，然后查看邮件。"]})

  lisa.define("personality", 
                        {"traits": [
                            "你充满好奇心，热爱学习新事物。",
                            "你善于分析，喜欢解决问题。",
                            "你友好随和，乐于与他人合作。",
                            "你不会轻易放弃，总能想方设法找到解决办法。不过，有时当事情进展不顺利时，你也会感到沮丧。"
                      ]})

  lisa.define("preferences", 
                        {"interests": [
                          "人工智能与机器学习。",
                          "自然语言处理与对话式智能体。",
                          "搜索引擎优化与用户体验。",
                          "烹饪和尝试新菜谱。",
                          "弹钢琴。",
                          "看电影，尤其是喜剧和惊悚片。"
                        ]})

你也可以将这两种方法结合起来，以 JSON 文件为基础，再通过编程方式添加或修改细节。

片段

TinyPerson 还可以通过 片段 进一步丰富，片段是一种可以添加到主规范中的子规范。这种方式有助于在不同智能体之间复用常见部分。例如，以下片段可用于描述对旅行的热爱（examples/fragments/travel_enthusiast.agent.fragment.json）：

{
    "type": "Fragment",
    "persona": {
        "preferences": {
            "interests": [
                "旅行",
                "探索新文化",
                "尝试当地美食"
            ],
            "likes": [
                "旅游指南",
                "规划行程和路线",
                "结识新朋友",
                "拍摄风景照片"
            ],
            "dislikes": [
                "拥挤的旅游景点",
                "突发的旅行中断",
                "高汇率"
            ]
        },
        "beliefs": [
            "旅行能够开阔眼界、丰富心灵。",
            "体验不同的文化有助于培养理解与同理心。",
            "冒险与探索是生活中不可或缺的一部分。",
            "即使不去那些地方，阅读旅游指南也是一件有趣的事。"
        ],
        "behaviors": {
            "travel": [
                "你会精心规划每一次旅行，仔细研究目的地和活动安排。",
                "你对即兴的冒险和临时改变路线持开放态度。",
                "你喜欢与当地人交流，了解他们的文化和传统。",
                "你会通过摄影和写日记记录自己的旅程。",
                "你更倾向于寻找地道的体验，而不是落入俗套的旅游陷阱。"
            ]
        }
    }
}

随后可以将其导入到代理中，如下所示：

lisa.import_fragment("./examples/fragments/travel_enthusiast.agent.fragment.json")

TinyPersonFactory

TinyPersonFactory 提供了一种强大的方式来利用大语言模型生成代理，这在为市场调研或其他模拟场景创建多样化人群时尤为有用。

from tinytroupe.factory import TinyPersonFactory

# 带有上下文的简单工厂
factory = TinyPersonFactory(context="圣保罗的一家医院。")
person = factory.generate_person("创造一个巴西人，他是医生，喜欢宠物和自然，并且热爱重金属音乐。")

对于市场调研和大型研究项目，你可以根据人口统计学信息创建工厂：

# 从人口统计数据（JSON文件或描述）创建工厂
factory = TinyPersonFactory.create_factory_from_demography(
    demography_description_or_file_path="./information/populations/usa.json",
    population_size=50,
    context="针对新产品的市场调研"
)

# 生成人群（默认并行化以加快速度）
people = factory.generate_people(number_of_people=50, parallelize=True, verbose=True)

parallelize 参数默认为 True，它通过并行调用 API 同时创建多个代理，从而显著加快人群生成速度。

该工厂会自动制定抽样计划，以确保多样性的体现。你可以查看这些内容：

# 查看抽样维度和计划
print(factory.sampling_dimensions)  # 用于多样性的维度
print(factory.sampling_plan)        # 代理将如何分布
print(factory.generated_minibios)   # 生成代理的简要摘要

TinyWorld

TinyWorld 是环境的基础类。以下是数据科学家 Lisa 和建筑师 Oscar 之间对话的一个示例。程序定义如下：

world = TinyWorld("聊天室", [lisa, oscar])
world.make_everyone_accessible()
lisa.listen("和Oscar聊聊，了解更多关于他的信息")
world.run(4)

这将产生以下对话：

用户 --> Lisa: [对话] 
          > 和Oscar聊聊，了解更多关于他的信息
────────────────────────────────────────────── 聊天室 第1步，共4步 ──────────────────────────────────────────────
Lisa --> Lisa: [思考] 
          > 我现在会稍微行动一下，然后发出完成指令。
Lisa 行动：[说话] 
          > 你好，Oscar！我很想多了解一下你。能跟我简单介绍一下你自己吗？
Lisa --> Lisa: [思考] 
          > 我现在会稍微行动一下，然后发出完成指令。
Lisa 行动：[完成] 

Lisa --> Oscar: [对话] 
          > 你好，Oscar！我很想多了解一下你。能跟我简单介绍一下你自己吗？
Oscar --> Oscar: [思考] 
           > 我现在会稍微行动一下，然后发出完成指令。
Oscar 行动：[说话] 
           > 你好，Lisa！当然可以，我很乐意跟你分享一些关于我的事。我叫Oscar，今年30岁，
           > 是来自德国的建筑师。我在一家名为Awesome Inc.的公司工作，主要负责设计
           > 新建公寓楼的标准构件。我喜欢现代主义建筑、新技术以及可持续发展的理念。业余时间，
           > 我喜欢去异国他乡旅行、弹吉他，还爱读科幻小说。那你呢？
Oscar --> Oscar: [思考] 
           > 我现在会稍微行动一下，然后发出完成指令。
Oscar 行动：[完成] 

Oscar --> Lisa: [对话] 
           > 你好，Lisa！当然可以，我很乐意跟你分享一些关于我的事。我叫Oscar，今年30岁，
           > 是来自德国的建筑师。我在一家名为Awesome Inc.的公司工作，主要负责设计
           > 新建公寓楼的标准构件。我喜欢现代主义建筑、新技术以及可持续发展的理念。业余时间，
           > 我喜欢去异国他乡旅行、弹吉他，还爱读科幻小说。那你呢？

TinyWorld 对可能的交互几乎没有限制。然而，其子类则应提供更为结构化的环境。 TinyWorld 对可能的交互几乎没有限制。然而，其子类则应提供更为结构化的环境。

交互式代理探索

TinyTroupe 提供了一个 Jupyter 小部件，用于与代理进行交互式对话，这对于探索代理行为和调试非常有用：

from tinytroupe.ui import AgentChatJupyterWidget

chat_interface = AgentChatJupyterWidget(people)  # 传入代理列表
chat_interface.display()

这将显示一个聊天界面，其中包含一个下拉菜单，用于选择代理并发送消息。

人群画像分析

使用 TinyPersonFactory 生成代理人群时，你可以利用 Profiler 分析特征分布：

from tinytroupe.profiling import Profiler

profiler = Profiler()
profiler.profile(people)  # 显示人口统计和特质分布

这有助于验证你生成的人群是否具备预期的多样性和特征。

成本跟踪

模拟可能会产生大量的 API 费用。TinyTroupe 在多个层面提供了成本跟踪功能：

from tinytroupe.clients import client

# API客户端级别的统计信息
client().pretty_print_cost_stats()

# 环境级别的统计信息
world.pretty_print_cost_stats()
TinyWorld.pretty_print_global_cost_stats()

# 代理级别的统计信息
TinyPerson.pretty_print_global_cost_stats()

行动质量控制

可以配置代理以检查和提升其行动的质量。这对于确保响应符合角色设定规范和预期格式非常有用：

# 针对每个代理配置质量控制
person.action_generator.enable_quality_checks = True
person.action_generator.quality_threshold = 5  # 1-10 分制
person.action_generator.max_attempts = 5
person.action_generator.enable_regeneration = True

你也可以通过 config.ini 或 config_manager 全局启用此功能：

from tinytroupe import config_manager

config_manager.update("action_generator_enable_quality_checks", True)
config_manager.update("action_generator_quality_threshold", 6)

实证验证

模拟中最重要的环节之一就是将结果与真实世界数据进行验证。TinyTroupe 提供了 SimulationExperimentEmpiricalValidator 类和 validate_simulation_experiment_empirically 函数，用于使用统计检验方法比较模拟输出与实证对照数据。

from tinytroupe.validation import SimulationExperimentEmpiricalValidator, validate_simulation_experiment_empirically

# 从 CSV 文件加载实证对照数据
control_data = SimulationExperimentEmpiricalValidator.read_empirical_data_from_csv(
    file_path="path/to/real_survey_data.csv",
    experimental_data_type="single_value_per_agent",  # 或 "ordinal_ranking_per_agent"
    agent_id_column="Responder #",
    value_column="Vote",
    agent_comments_column="Explanation",
    dataset_name="Real Survey"
)

# 从模拟结果中创建处理组数据（假设 df 包含模拟结果）
treatment_data = SimulationExperimentEmpiricalValidator.read_empirical_data_from_dataframe(
    df=simulation_results_df,
    experimental_data_type="single_value_per_agent",
    agent_id_column="name",
    value_column="Vote",
    dataset_name="Simulation Results"
)

# 运行统计验证（默认为 t 检验，或 ks 检验）
result = validate_simulation_experiment_empirically(
    control_data=control_data,
    treatment_data=treatment_data,
    validation_types=["statistical"],
    statistical_test_type="t_test",  # 或 "ks_test"
    output_format="values"
)

# 访问结果
print(result.overall_score)
print(result.statistical_results)

这使你可以定量评估模拟结果与现实行为的匹配程度，从而增强对基于模拟洞察的信心。

缓存

调用 LLM API 可能成本较高，因此缓存策略对于降低这些成本非常重要。TinyTroupe 提供两种缓存机制：一种用于模拟状态，另一种用于 LLM 调用本身。

模拟状态缓存

设想你有一个包含 10 个步骤的场景，已经完成了前 9 步的工作，现在正准备微调第 10 步。为了正确验证你的修改，当然需要重新运行整个模拟。然而，既然前 9 步的结果已经满意且未做任何更改，那么为何还要再次执行它们并产生 LLM 费用呢？针对这类情况，tinytroupe.control 模块提供了实用的模拟管理方法：

• control.begin("<CACHE_FILE_NAME>.cache.json")：开始记录模拟的状态变化，并将其保存到指定的磁盘文件中。
• control.checkpoint()：保存当前的模拟状态。
• control.end()：结束由 control.begin() 启动的模拟状态记录范围。

LLM API 调用缓存

此功能最好在 config.ini 文件中通过设置 CACHE_API_CALLS=True 来启用。

启用后，LLM API 缓存的工作原理比模拟状态缓存更简单直接：每次 LLM 调用都会被存储在一个从输入到输出的映射表中；当新的调用与之前某次调用完全相同，就会直接返回缓存的值。

Config.ini

config.ini 文件包含了多种可用于自定义库行为的参数，例如模型参数和日志级别。请特别注意 API_TYPE 参数，它决定了你是使用 Azure OpenAI 服务还是 OpenAI API。目前默认设置为 openai（OpenAI API）。

关键配置部分包括：

• [OpenAI]：API 设置、模型选择及参数
• [Simulation]：并行执行与安全设置
• [Cognition]：记忆管理设置
• [ActionGenerator]：行动质量控制与纠正机制
• [Logging]：日志级别配置

默认使用的模型：

• MODEL=gpt-5-mini：用于生成代理回复的主要文本生成模型（之前的默认值 gpt-4.1-mini 现已过时但仍受支持）
• EMBEDDING_MODEL=text-embedding-3-small：用于文本相似度任务
• REASONING_MODEL=o3-mini：用于详细分析和推理任务（仍处于实验阶段，暂不推荐使用）

我们提供了一个示例 config.ini 文件，位于 ./examples/config.ini，你可以将其作为自己的模板，或者直接修改以运行示例代码。

程序化配置覆盖

除了静态的 config.ini 文件外，你还可以使用 config_manager 对许多配置值进行程序化覆盖。这在运行时动态调整配置或为特定实验设置参数时非常有用：

from tinytroupe import config_manager

# 程序化覆盖配置值
config_manager.update("action_generator_enable_quality_checks", True)
config_manager.update("action_generator_quality_threshold", 6)
config_manager.update("cache_api_calls", True)

这种方法允许你：

• 在不修改配置文件的情况下尝试不同的设置
• 在模拟执行过程中动态应用配置变更
• 在保持其他配置不变的情况下覆盖特定参数
• 根据运行时条件实施条件性配置

程序化覆盖会优先于 config.ini 文件中的值，从而让你能够针对特定用例或实验精细调整行为。

其他实用工具

TinyTroupe 提供了上述未详细提及的额外实用工具和便利功能：

• TinyTool：模拟工具，可供 TinyPerson 使用。
• TinyStory：帮助您创建和管理通过模拟讲述的故事。
• TinyPersonValidator：帮助您验证 TinyPerson 的行为。
• ResultsExtractor 和 ResultsReducer：提取并归纳智能体之间交互的结果。
• ArtifactExporter：将模拟生成的成果（文档、数据）导出到文件中。
• 心智能力模块（TinyToolUse、FilesAndWebGroundingFaculty）：通过工具使用和知识增强扩展智能体的能力。
• ……以及其他更多……

通常，代表模拟实体或辅助机制的组件会以 Tiny 作为前缀，而更偏向基础设施性质的组件则不加前缀。这一命名规则强调了属于模拟系统本身的元素的模拟特性。

贡献说明

本项目欢迎各类贡献与建议。大多数贡献都需要您签署一份贡献者许可协议（CLA），声明您有权且确实授予我们使用您贡献内容的权利。有关详情，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标记您的 PR（例如添加状态检查或评论）。请按照机器人提供的指示操作即可。对于所有使用我们 CLA 协议的仓库，您只需完成一次此步骤。

本项目已采纳 微软开源行为准则。如需更多信息，请参阅 行为准则常见问题解答 或发送邮件至 opencode@microsoft.com 咨询其他问题或意见。

贡献的内容与方式

我们欢迎各种形式的贡献，但目前主要寻找新颖有趣的用例演示，甚至只是特定领域的应用创意。如果您是某个可以从 TinyTroupe 中受益的领域的专家，我们非常期待您的反馈。

除此之外，还有许多方面可以进一步改进，例如：

• 记忆机制。
• 数据增强机制。
• 推理机制。
• 新型环境类型。
• 与外部世界的交互接口。
• ……以及其他更多……

请注意，您贡献的任何内容都可能以开源形式发布（采用 MIT 许可证）。

如果您希望做出贡献，请尽量遵循以下通用指南：

• Tiny 命名规范：如果您正在实现面向实验者的模拟元素（例如智能体或环境类型）或与其密切相关的组件（如智能体工厂或内容丰富器），并且名称合适，不妨将其命名为 TinyXYZ :-) 另一方面，辅助性和基础设施类的机制则不应以 “Tiny” 作为前缀。这样做的目的是突出那些属于模拟系统本身的元素的模拟特性。
• 测试：如果您编写了新的机制，请至少在 tests/unit/ 目录下创建单元测试；如果可能，也请添加功能场景测试（tests/scenarios/）。
• 示例展示：如果您想演示一个新的场景，请尽量将其设计为 examples/ 目录下的新 Jupyter 笔记本。
• 微软相关：如果您实现了任何与微软相关且非机密的内容，请将其放置在 .../microsoft/ 文件夹中。

致谢

TinyTroupe 最初源于微软内部黑客马拉松项目，随后逐步发展壮大。目前，TinyTroupe 核心团队由以下成员组成：

• Paulo Salem（TinyTroupe 的创始人兼现任负责人）
• Christopher Olsen（工程/科学部门）
• Yi Ding（产品管理）
• Prerit Saxena（工程/科学部门）

当前顾问：

• Robert Sim（工程/科学部门）

此外，以下人员也做出了特别贡献：

• Nilo Garcia Silveira：最初的智能体验证思路及相关实现；总体的初步反馈与见解；名称建议。
• Olnei Fonseca：最初的智能体验证思路；总体的初步反馈与见解；名称建议。
• Robert Sim：合成数据生成场景的专业知识及实现。
• Paulo Freire：合成数据生成示例的专业知识及实现。
• Carlos Costa：合成数据生成场景的专业知识及实现。
• Bryant Key：广告场景领域的专业知识与见解。
• Barbara da Silva：与智能体内存管理相关的实现。

…—您是否觉得这里还缺少某位贡献者？请提醒我们！

引用 TinyTroupe

在您的工作中使用 TinyTroupe 时，请引用其介绍性论文。该论文目前正在审稿中，但您可以在 Arxiv 上找到预印本。

Paulo Salem, Robert Sim, Christopher Olsen, Prerit Saxena, Rafael Barcelos, Yi Ding. (2025). TinyTroupe：一个基于 LLM 的多智能体角色模拟工具包。ArXiv 预印本：2507.09788。GitHub 仓库地址：https://github.com/microsoft/TinyTroupe。

以 BibTeX 格式，您可以使用以下条目：

@article{tinytroupe2025,
  author       = {Paulo Salem and Robert Sim and Christopher Olsen and Prerit Saxena and Rafael Barcelos and Yi Ding},
  title        = {TinyTroupe: An LLM-powered Multiagent Persona Simulation Toolkit},
  journal      = {arXiv preprint arXiv:2507.09788},
  year         = {2025},
  archivePrefix= {arXiv},
  eprint       = {2507.09788},
  note         = {GitHub repository: \url{https://github.com/microsoft/TinyTroupe}}
}

法律免责声明

TinyTroupe 仅用于研究和模拟目的。它是一项研究性和实验性的技术，依赖于人工智能（AI）模型生成文本内容。AI 系统的输出可能包含不现实、不当、有害或不准确的结果，包括事实性错误。在使用生成内容之前，您有责任对其进行审查（并在必要时进行调整），因为您需对内容的准确性及其适用性承担全部责任。我们建议将 TinyTroupe 的输出用于洞察生成，而非直接决策。生成的内容并不代表微软的观点。您应对所使用的所有生成内容承担全部责任。有关负责任地使用该技术的更多信息，请参阅 RESPONSIBLE_AI_FAQ.md。

禁止用途： TinyTroupe 不应用于模拟敏感场景（例如暴力或性相关场景）。此外，不得利用其输出故意欺骗、误导或以任何方式伤害他人。您需对自身的所有使用行为承担全部责任，并遵守所有适用的法律法规。

商标

本项目可能包含项目、产品或服务的商标或标识。微软商标或标识的授权使用须遵守并依据 微软商标与品牌指南。 在本项目的修改版本中使用微软商标或标识时，不得造成混淆或暗示微软的赞助关系。 任何第三方商标或标识的使用均须遵循该第三方的相关政策。

TinyTroupe 快速上手指南

TinyTroupe 是一个由微软开发的实验性 Python 库，利用大语言模型（如 GPT-4/GPT-5）模拟具有特定性格、兴趣和目标的虚拟人物（TinyPerson）。它适用于广告评估、软件测试、合成数据生成、产品反馈及头脑风暴等场景，旨在通过多智能体仿真增强人类想象力并获取商业洞察。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows, macOS 或 Linux。
• Python 版本：建议安装 Python 3.10 或更高版本。
• 依赖项：
  • pip (Python 包管理工具)
  • LLM API Key：默认需要 OpenAI API Key（支持 GPT-4o-mini, GPT-4.1-mini, GPT-5-mini 等）。
  • (可选) 若需使用本地模型，可配置 Ollama。
• 推荐工具：Jupyter Notebook 或 JupyterLab（官方示例多为 Notebook 格式，且深色主题视觉效果更佳）。

安装步骤

1. 克隆仓库

首先从 GitHub 克隆项目代码：

git clone https://github.com/microsoft/TinyTroupe.git
cd TinyTroupe

2. 创建虚拟环境（推荐）

为避免依赖冲突，建议创建独立的虚拟环境：

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

3. 安装依赖

安装项目所需的 Python 包：

pip install -r requirements.txt

提示：如果下载速度较慢，可使用国内镜像源加速安装：

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

4. 配置 API Key

TinyTroupe 默认通过环境变量或配置文件读取 LLM API Key。

方法 A：设置环境变量（推荐）

# Windows (PowerShell)
$env:OPENAI_API_KEY="sk-your-api-key-here"

# macOS/Linux
export OPENAI_API_KEY="sk-your-api-key-here"

方法 B：修改配置文件 复制示例配置文件并根据需要编辑：

cp config.ini.example config.ini

在 config.ini 中填入您的 OPENAI_API_KEY 并确认默认模型设置（注意：新版本默认模型可能已更新为 gpt-5-mini 或 gpt-4.1-mini，请根据实际可用模型调整）。

基本使用

最简单的方式是通过 Python 脚本或 Jupyter Notebook 创建一个虚拟人物并进行对话。

示例：创建人物并访谈

以下代码演示了如何定义一个具有特定人设的 TinyPerson，并在模拟环境中与其交互：

import tinytroupe as tt

# 1. 初始化环境 (自动读取配置中的 API Key)
tt.init()

# 2. 定义一个人物 (TinyPerson)
# 可以指定姓名、职业、性格特征、目标等
customer = tt.TinyPerson(
    name="张伟",
    occupation="银行经理",
    traits=["谨慎", "注重数据", "忙碌"],
    goals=["寻找高效的数字化转型方案", "降低运营成本"]
)

# 3. 创建咨询师角色 (也可以由用户直接扮演)
consultant = tt.TinyPerson(
    name="李顾问",
    occupation="IT 咨询顾问",
    traits=["专业", "善于倾听", "结果导向"]
)

# 4. 开始对话模拟
# 让咨询师向客户提问
response = consultant.listen_and_reply("张经理您好，听说贵行最近在考虑数字化转型，能具体聊聊您最关心的痛点吗？", 
                                       audience=[customer])

print(f"客户回复：{response}")

# 5. 继续多轮对话以深入挖掘需求
# 客户继续回应
next_response = customer.listen_and_reply(response, audience=[consultant])
print(f"客户进一步说明：{next_response}")

运行示例笔记本

项目包含了丰富的预置案例，建议在 examples/ 目录下运行 Jupyter Notebook 以体验完整功能（如广告评估、焦点小组模拟等）：

jupyter notebook examples/Interview\ with\ Customer.ipynb

注意：TinyTroupe 目前处于活跃开发阶段（Work in Progress），API 可能会有频繁变动。建议在使用前查阅最新的 examples 文件夹以获取符合当前版本的用法。