TinyTroupe 🤠🤓🥸🧐

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

[!TIP]
📄 新论文发布！ 查看我们的 TinyTroupe 论文（预印本），其中详细描述了该库及其用例。你可以在 publications/ 文件夹中找到相关实验和补充材料。

TinyTroupe 是一个实验性的 Python 库，用于模拟具有特定个性、兴趣和目标的人。这些人工智能体——TinyPerson——可以倾听我们和彼此，进行回复，并在模拟的 TinyWorld 环境中生活。这是通过利用大语言模型（LLMs，特别是 GPT-4）的能力来生成逼真的模拟行为实现的。这使我们能够在我们选择的条件下，研究具有高度可定制角色的广泛令人信服的交互和消费者类型。因此，重点在于理解人类行为，而不是直接支持它（例如，像 AI 助手那样）——这导致了，除其他外，仅在模拟环境中才有意义的专门机制。此外，与其他基于 LLM 的游戏式模拟方法不同，TinyTroupe 旨在启发生产力和商业场景，从而为更成功的项目和产品做出贡献。以下是一些增强人类想象力的应用构想：

• 广告： TinyTroupe 可以在花钱之前，用模拟受众离线评估数字广告（例如，Bing Ads）！
• 软件测试： TinyTroupe 可以向系统（例如，搜索引擎、聊天机器人或副驾驶）提供测试输入，然后评估结果。
• 训练和探索性数据： TinyTroupe 可以生成逼真的合成数据，这些数据随后可用于训练模型或进行机会分析。
• 产品和项目管理： TinyTroupe 可以阅读项目或产品提案，并从特定角色（例如，医生、律师和一般知识工作者）的角度提供反馈。
• 头脑风暴： TinyTroupe 可以模拟焦点小组，并以极低的成本提供出色的产品反馈！

在上述所有场景以及许多其他场景中，我们希望实验者能够获得对其感兴趣领域的洞察，从而做出更好的决策。

我们在相对较早的阶段发布 TinyTroupe，仍有大量工作要做，因为我们正在寻求反馈和贡献，以引导开发朝着富有成效的方向发展。我们特别有兴趣发现新的潜在用例，例如在特定行业中。

[!NOTE]
🚧 进行中的工作：预计会有频繁变更。
TinyTroupe 是一个正在进行的研究项目，仍处于非常重要的开发阶段，需要进一步整理。特别是，API 仍可能频繁更改。尝试 API 变体对于正确塑造它至关重要，但我们正在努力稳定它，并随着时间的推移提供更一致和友好的体验。在我们持续改进库的过程中，感谢您的耐心和反馈。

[!CAUTION]
⚖️ 请阅读法律免责声明。
TinyTroupe 仅用于研究和模拟。您对生成的输出的任何使用承担全部责任。各种重要的额外法律考虑因素适用并限制其使用。在使用 TinyTroupe 之前，请阅读下面的完整法律免责声明部分。

目录

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

最新消息

[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 等）。
- 现在通过 LLMChat 类以及 @llm 装饰器更好地支持内部 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/ 文件夹中的示例，以及笔记本 政治指南针（使用片段自定义智能体） 进行演示。
- 引入基于 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 故事讲述设备选项，然后将模拟结果与真实调查数据进行比较：

使用 Borda 计数和首选份额分析，我们可以比较模拟偏好与真实偏好的匹配程度：

您可以在 examples/ 文件夹中找到其他示例。

先决条件

运行该库需要：
- Python 3.10 或更高版本。我们假设您使用 Anaconda，但您也可以使用其他 Python 发行版。
- 访问 Azure OpenAI Service 或 OpenAI GPT-4 API。您可以在此处获取 Azure OpenAI Service 的访问权限此处，以及 OpenAI API 的访问权限此处。
* 对于 Azure OpenAI Service，您需要将 AZURE_OPENAI_KEY 和 AZURE_OPENAI_ENDPOINT 环境变量分别设置为您的 API 密钥和端点。
* 对于 OpenAI，您需要将 OPENAI_API_KEY 环境变量设置为您的 API 密钥。
- 默认情况下，TinyTroupe 的 config.ini 设置为使用 OpenAI API，并将 gpt-5-mini 作为主要模型。之前的默认模型（gpt-4.1-mini）现在被视为旧版，但预计仍可工作。您可以通过在运行的程序或笔记本所在文件夹中包含您自己的 config.ini 文件来自定义这些值。examples/ 文件夹中提供了一个 config.ini 文件示例。

[!IMPORTANT]
内容过滤器： 为确保在模拟过程中不生成有害内容，强烈建议在 API 级别使用内容过滤器（如果可用）。特别是，如果使用 Azure OpenAI，有广泛的内容审核支持，我们强烈建议您使用它。 有关如何操作的详细信息，请查阅相应的 Azure OpenAI 文档。如果启用了内容过滤器，并且 API 调用被它们拒绝，库将引发异常，因为此时无法继续进行模拟。

Ollama 支持

TinyTroupe 的开发主要考虑 OpenAI 模型和兼容的端点，以简化开发并专注于充分利用特定模型，而不是投入时间尝试使其与任何模型都能良好工作（这可能不可行）。因此，如果可以，请使用 OpenAI 模型和兼容的端点。 话虽如此，社区对本地模型支持的需求很大，因此我们现在正在尝试通过部分 Ollama 支持和社区贡献者的帮助来实现这一点。此外，使用本地模型的另一个原因是对专门为角色模拟设计的自定义模型进行研究——最终，这可能是支持此类功能的最佳理由。无论如何，目前这对核心团队来说不是优先事项，尽管我们正在尽我们所能允许这种可能性。

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

安装

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

1. 如果未安装 Conda，可以从此处获取。您也可以使用其他 Python 发行版，但为简单起见，我们在此假设使用 Conda。
2. 创建一个新的 Python 环境：
   bash conda create -n tinytroupe python=3.10
3. 激活环境：
   bash conda activate tinytroupe
4. 确保您已按照先决条件部分的描述，将 Azure OpenAI 或 OpenAI API 密钥设置为环境变量。
5. 使用 pip 直接从该仓库安装库（我们不会从 PyPI 安装）：
   bash pip install git+https://github.com/microsoft/TinyTroupe.git@main

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

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

安装后运行示例

要实际运行示例，您需要将它们下载到本地计算机。您可以通过克隆仓库来实现：

1. 克隆仓库，因为我们将执行本地安装（我们不会从 PyPI 安装）：
   bash git clone https://github.com/microsoft/tinytroupe cd tinytroupe
2. 您现在可以运行 examples/ 文件夹中的示例，或者修改它们以创建您自己的自定义模拟。

本地开发

如果您想修改 TinyTroupe 本身，可以以可编辑模式安装（即，代码更改将立即反映）：
1. 克隆仓库，因为我们将执行本地安装（我们不会从 PyPI 安装）：
bash git clone https://github.com/microsoft/tinytroupe cd tinytroupe
2. 以可编辑模式安装库：
bash pip install -e .

设计原则

最近，我们看到 LLMs 被用来模拟人（例如这个），但主要是在“游戏式”环境中用于沉思或娱乐目的。还有一些用于构建多智能体系统以解决问题和提供辅助 AI 的库，如 [Autogen](https://microsoft.github.io/