定理解释代理 (TEA) 🍵

🌐 主页 | 📖 arXiv | 🤗 HuggingFace 数据集 | 🎥视频数据 | ▶️ YouTube

本仓库包含我们论文《TheoremExplainAgent: 面向LLM定理理解的基于视频的多模态解释》的代码库（https://arxiv.org/abs/2502.19400）。

ACL 2025 主会（口头报告）

简介

TheoremExplainAgent 是一种人工智能系统，能够生成长篇的 Manim 视频来直观地解释定理，在展示其深度理解的同时，揭示仅靠文本难以发现的推理漏洞。

https://github.com/user-attachments/assets/17f2f4f2-8f2c-4abc-b377-ac92ebda69f3

📰 新闻

• 2025年6月24日：论文被选为口头报告（前3%）。
• 2025年6月8日：我们发布了生成的视频数据，供研究人员作为基线参考。
• 2025年5月15日：论文被接受至 ACL 2025 主会。
• 2025年3月3日：生成代码和评估代码发布。感谢大家的耐心等待！

• 2025年2月27日：论文已在 Arxiv 上发布。感谢 AK 将我们的论文刊登在 HF Daily 上。

下载生成的视频数据

如果您只想试用代码，请跳过本节。 如果您是研究人员，只需要这些基线视频作为对比基准，请在此处下载：

wget --save-cookies /tmp/cookies.txt --keep-session-cookies --no-check-certificate 'https://docs.google.com/uc?export=download&id=18kmzXvbxaFGyJw-g51jnq9m93v_ez4aJ' -O /tmp/gdrive.html && wget --load-cookies /tmp/cookies.txt -O baseline_videos.zip "https://drive.usercontent.google.com/download?id=18kmzXvbxaFGyJw-g51jnq9m93v_ez4aJ&export=download&confirm=$(sed -rn 's/.*name="confirm" value="([^"]+)".*/\\1/p' /tmp/gdrive.html)&uuid=$(sed -rn 's/.*name="uuid" value="([^"]+)".*/\\1/p' /tmp/gdrive.html)" && rm /tmp/gdrive.html /tmp/cookies.txt

安装

如果您遇到任何问题，请查看此 README 文档中的【FAQ】部分
如果仍无法解决，请创建一个 issue

1. 设置 conda 环境

conda create --name tea python=3.12.8
conda activate tea
pip install -r requirements.txt

2. 您可能还需要安装 LaTeX 和其他 Manim Community 的依赖项。更多详情请参阅 Manim 安装文档。

# 如果您使用的是 Linux Ubuntu，可能需要以下依赖：
sudo apt-get install portaudio19-dev
sudo apt-get install libsdl-pango-dev

3. 接着使用以下命令下载 Kokoro 模型和语音文件，以启用 TTS 服务。

mkdir -p models && wget -P models https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/kokoro-v0_19.onnx && wget -P models https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/voices.bin

4. 根据 .env.template 文件创建 .env 文件，并按照您选择使用的模型填写环境变量。 可参考 LiteLLM 文档。

touch .env

然后打开 .env 文件，使用您喜欢的文本编辑器进行编辑。

您的 .env 文件应如下所示：

# OpenAI
OPENAI_API_KEY=""

# Azure OpenAI
AZURE_API_KEY=""
AZURE_API_BASE=""
AZURE_API_VERSION=""

# Google Vertex AI
VERTEXAI_PROJECT=""
VERTEXAI_LOCATION=""
GOOGLE_APPLICATION_CREDENTIALS=""

# Google Gemini
GEMINI_API_KEY=""

...

# Kokoro TTS 设置
KOKORO_MODEL_PATH="models/kokoro-v0_19.onnx"
KOKORO_VOICES_PATH="models/voices.bin"
KOKORO_DEFAULT_VOICE="af"
KOKORO_DEFAULT_SPEED="1.0"
KOKORO_DEFAULT_LANG="en-us"

请根据您要使用的模型填写相应的 API 密钥。

5. 配置 Python 路径。请注意，您需要配置 Python 路径才能正常运行。否则可能会遇到导入问题（例如无法导入 src 等）。

export PYTHONPATH=$(pwd):$PYTHONPATH

6. （可选）若需设置 RAG，请参阅 https://github.com/TIGER-AI-Lab/TheoremExplainAgent?tab=readme-ov-file#generation-with-rag。

如果您遇到任何问题，请查看此 README 文档中的【FAQ】部分
如果仍无法解决，请创建一个 issue

生成

支持的模型

模型命名遵循 LiteLLM 规范。有关模型命名的详细信息，请参阅 LiteLLM 文档。

单主题生成

python generate_video.py \
      --model "openai/o3-mini" \
      --helper_model "openai/o3-mini" \
      --output_dir "output/your_exp_name" \
      --topic "your_topic" \
      --context "description of your topic, e.g. 'This is a topic about the properties of a triangle'" \

示例：

python generate_video.py \
      --model "openai/o3-mini" \
      --helper_model "openai/o3-mini" \
      --output_dir "output/my_exp_name" \
      --topic "大 O 记号" \
      --context "计算机科学中用于衡量最坏情况复杂度最常见的渐近符号" \

批量生成

python generate_video.py \
      --model "openai/o3-mini" \
      --helper_model "openai/o3-mini" \
      --output_dir "output/my_exp_name" \
      --theorems_path data/thb_easy/math.json \
      --max_scene_concurrency 7 \
      --max_topic_concurrency 20 \

使用 RAG 生成视频

在使用 RAG 之前，请从此 Google Drive 链接 下载 RAG 文档。下载后，请解压文件。例如，如果将其解压到 data/rag/manim_docs，则应将 --manim_docs_path 设置为 data/rag/manim_docs。向量数据库将在首次运行 RAG 时创建。

python generate_video.py \
            --model "openai/o3-mini" \
            --helper_model "openai/o3-mini" \
            --output_dir "output/with_rag/o3-mini/vtutorbench_easy/math" \
            --topic "大 O 表示法" \
            --context "计算机科学中用于衡量最坏情况复杂度的最常见的渐近符号类型" \
            --use_rag \
            --chroma_db_path "data/rag/chroma_db" \
            --manim_docs_path "data/rag/manim_docs" \
            --embedding_model "vertex_ai/text-embedding-005"

我们支持更多生成选项，详情如下：

usage: generate_video.py [-h]
                         [--model]
                         [--topic TOPIC] [--context CONTEXT]
                         [--helper_model]
                         [--only_gen_vid] [--only_combine] [--peek_existing_videos] [--output_dir OUTPUT_DIR] [--theorems_path THEOREMS_PATH]
                         [--sample_size SAMPLE_SIZE] [--verbose] [--max_retries MAX_RETRIES] [--use_rag] [--use_visual_fix_code]
                         [--chroma_db_path CHROMA_DB_PATH] [--manim_docs_path MANIM_DOCS_PATH]
                         [--embedding_model {azure/text-embedding-3-large,vertex_ai/text-embedding-005}] [--use_context_learning]
                         [--context_learning_path CONTEXT_LEARNING_PATH] [--use_langfuse] [--max_scene_concurrency MAX_SCENE_CONCURRENCY]
                         [--max_topic_concurrency MAX_TOPIC_CONCURRENCY] [--debug_combine_topic DEBUG_COMBINE_TOPIC] [--only_plan] [--check_status]
                         [--only_render] [--scenes SCENES [SCENES ...]]

使用 AI 生成 Manim 视频

options:
  -h, --help            显示此帮助信息并退出
  --model               选择要使用的 AI 模型
  --topic TOPIC         要生成视频的主题
  --context CONTEXT     主题的背景信息
  --helper_model        选择要使用的辅助模型
  --only_gen_vid        仅根据现有计划生成视频
  --only_combine        仅合并视频
  --peek_existing_videos, --peek
                        查看现有视频
  --output_dir OUTPUT_DIR
                        输出目录
  --theorems_path THEOREMS_PATH
                        定理 JSON 文件的路径
  --sample_size SAMPLE_SIZE, --sample SAMPLE_SIZE
                        要采样的定理数量
  --verbose             打印详细输出
  --max_retries MAX_RETRIES
                        代码生成的最大重试次数
  --use_rag, --rag      使用检索增强生成
  --use_visual_fix_code, --visual_fix_code
                        使用 VLM 根据渲染后的画面修复代码
  --chroma_db_path CHROMA_DB_PATH
                        Chroma DB 的路径
  --manim_docs_path MANIM_DOCS_PATH
                        Manim 文档的路径
  --embedding_model {azure/text-embedding-3-large,vertex_ai/text-embedding-005}
                        选择要使用的嵌入模型
  --use_context_learning
                        使用示例 Manim 代码进行上下文学习
  --context_learning_path CONTEXT_LEARNING_PATH
                        上下文学习示例的路径
  --use_langfuse        启用 Langfuse 日志记录
  --max_scene_concurrency MAX_SCENE_CONCURRENCY
                        可同时处理的最大场景数
  --max_topic_concurrency MAX_TOPIC_CONCURRENCY
                        可同时处理的最大主题数
  --debug_combine_topic DEBUG_COMBINE_TOPIC
                        调试合并视频
  --only_plan           仅生成场景大纲和实现计划
  --check_status        检查所有定理的规划和代码状态
  --only_render         仅渲染场景，不合并视频
  --scenes SCENES [SCENES ...]
                        要处理的具体场景（如果提供了 theorems_path）

评估

请注意，评估需要使用 Gemini 和 GPT4o。

目前，评估需要一个视频文件和一个字幕文件（SRT 格式）。

视频评估：

用法：evaluate.py [-h]
                   [--model_text {gemini/gemini-1.5-pro-002,gemini/gemini-1.5-flash-002,gemini/gemini-2.0-flash-001,vertex_ai/gemini-1.5-flash-002,vertex_ai/gemini-1.5-pro-002,vertex_ai/gemini-2.0-flash-001,openai/o3-mini,gpt-4o,azure/gpt-4o,azure/gpt-4o-mini,bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0,bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0,bedrock/anthropic.claude-3-5-haiku-20241022-v1:0,bedrock/us.anthropic.claude-3-7-sonnet-20250219-v1:0}]
                   [--model_video {gemini/gemini-1.5-pro-002,gemini/gemini-2.0-flash-exp,gemini/gemini-2.0-pro-exp-02-05}]
                   [--model_image {gemini/gemini-1.5-pro-002,gemini/gemini-1.5-flash-002,gemini/gemini-2.0-flash-001,vertex_ai/gemini-1.5-flash-002,vertex_ai/gemini-1.5-pro-002,vertex_ai/gemini-2.0-flash-001,openai/o3-mini,gpt-4o,azure/gpt-4o,azure/gpt-4o-mini,bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0,bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0,bedrock/anthropic.claude-3-5-haiku-20241022-v1:0,bedrock/us.anthropic.claude-3-7-sonnet-20250219-v1:0}]
                   [--eval_type {text,video,image,all}] --file_path FILE_PATH --output_folder OUTPUT_FOLDER [--retry_limit RETRY_LIMIT] [--combine] [--bulk_evaluate] [--target_fps TARGET_FPS]
                   [--use_parent_folder_as_topic] [--max_workers MAX_WORKERS]

使用 LLM 自动评估定理解释视频

选项：
  -h, --help            显示此帮助消息并退出
  --model_text {gemini/gemini-1.5-pro-002,gemini/gemini-1.5-flash-002,gemini/gemini-2.0-flash-001,vertex_ai/gemini-1.5-flash-002,vertex_ai/gemini-1.5-pro-002,vertex_ai/gemini-2.0-flash-001,openai/o3-mini,gpt-4o,azure/gpt-4o,azure/gpt-4o-mini,bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0,bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0,bedrock/anthropic.claude-3-5-haiku-20241022-v1:0,bedrock/us.anthropic.claude-3-7-sonnet-20250219-v1:0}
                        选择用于文本评估的 AI 模型
  --model_video {gemini/gemini-1.5-pro-002,gemini/gemini-2.0-flash-exp,gemini/gemini-2.0-pro-exp-02-05}
                        选择用于视频评估的 AI 模型
  --model_image {gemini/gemini-1.5-pro-002,gemini/gemini-1.5-flash-002,gemini/gemini-2.0-flash-001,vertex_ai/gemini-1.5-flash-002,vertex_ai/gemini-1.5-pro-002,vertex_ai/gemini-2.0-flash-001,openai/o3-mini,gpt-4o,azure/gpt-4o,azure/gpt-4o-mini,bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0,bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0,bedrock/anthropic.claude-3-5-haiku-20241022-v1:0,bedrock/us.anthropic.claude-3-7-sonnet-20250219-v1:0}
                        选择用于图像评估的 AI 模型
  --eval_type {text,video,image,all}
                        要执行的评估类型
  --file_path FILE_PATH
                        文件或定理文件夹的路径
  --output_folder OUTPUT_FOLDER
                        存储评估文件的目录
  --retry_limit RETRY_LIMIT
                        每次推理的重试次数
  --combine             将所有结果合并到一个 JSON 文件中
  --bulk_evaluate       一起评估一个定理文件夹
  --target_fps TARGET_FPS
                        视频处理的目标帧率。如果不设置，则使用原始视频的帧率
  --use_parent_folder_as_topic
                        对单个文件进行评估时，将父文件夹名称用作主题名称
  --max_workers MAX_WORKERS
                        并行处理的最大工作线程数

• 对于 file_path，建议传递一个同时包含 MP4 文件和 SRT 文件的文件夹。

杂项：修改 TheoremExplainAgent 中的系统提示

如果您想修改系统提示，您需要：

1. 修改 task_generator/prompts_raw 文件夹中的文件。
2. 运行 task_generator/parse_prompt.py 以重新构建 __init__.py 文件。

cd task_generator
python parse_prompt.py
cd ..

TheoremExplainBench (TEB)

TheoremExplainBench 可以在 https://huggingface.co/datasets/TIGER-Lab/TheoremExplainBench 上找到。

使用方法：

import datasets
dataset = datasets.load_dataset("TIGER-Lab/TheoremExplainBench")

数据集信息：

DatasetDict({
    train: Dataset({
        features: ['uid', 'subject', 'difficulty', 'theorem', 'description', 'subfield'],
        num_rows: 240
    })
})

❓ 常见问题解答

常见问题解答应涵盖您可能遇到的最常见错误。如果您遇到新的问题，请在 issues 中报告。

问：错误 src.utils.kokoro_voiceover import KokoroService # 您必须这样导入，因为这是我们的自定义配音服务。 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ModuleNotFoundError: 没有名为 'src' 的模块。
答：请在启动新终端时运行 export PYTHONPATH=$(pwd):$PYTHONPATH。

问：错误 未找到文件。
答：请检查您的 Manim 安装。

问：错误 latex ...。
答：请检查您的 LaTeX 安装。

问：输出日志没有显示响应？
答：这可能是 API 相关的问题。请确保您的 .env 文件配置正确（填写您的 API 密钥），或者您可以启用 litellm 调试模式来找出问题所在。

问：计划 / 场景缺失？
答：这可能是 API 相关的问题。请确保您的 .env 文件配置正确（填写您的 API 密钥），或者您可以启用 litellm 调试模式来找出问题所在。

🖊️ 引用

如果您使用我们的代码、数据、模型或结果，请务必引用我们的论文：

@misc{ku2025theoremexplainagentmultimodalexplanationsllm,
      title={TheoremExplainAgent: 向多模态解释迈进——用于 LLM 定理理解}, 
      author={Max Ku 和 Thomas Chong 和 Jonathan Leung 和 Krish Shah 和 Alvin Yu 和 Wenhu Chen},
      year={2025},
      eprint={2502.19400},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2502.19400}, 
}

🎫 许可证

本项目采用 MIT 许可证 发布。

⭐ 星标历史

💞 致谢

我们感谢 Votee AI 捐赠了用于访问闭源模型的 API 密钥。

本代码基于以下仓库构建，我们感谢所有贡献者将其开源：

• Manim Community
• kokoro-manim-voiceover
• manim-physics
• manim-Chemistry
• ManimML
• manim-dsa
• manim-circuit

🚨 免责声明

本作品仅用于研究目的。作者不鼓励也不支持将此代码库用于商业用途。代码按“原样”提供，不提供任何担保，用户需自行承担使用该代码的所有责任。

测试环境：MacOS、Linux

TheoremExplainAgent (TEA) 快速上手指南

TheoremExplainAgent 是一个 AI 系统，能够生成长格式的 Manim 动画视频，以可视化方式解释数学定理，展示大模型对定理的深度理解。

环境准备

系统要求

• 操作系统: 推荐 Linux (Ubuntu)，Windows/macOS 可能需要额外配置 Manim 依赖。
• Python 版本: 3.12.8 (必须严格匹配)。
• 磁盘空间: 需预留足够空间存放模型文件及生成的视频数据。

前置依赖

在开始安装前，请确保系统已安装以下基础工具：

• Conda: 用于管理 Python 环境。
• LaTeX: Manim 渲染视频所必需（如 texlive）。
• 系统库 (Ubuntu):

  sudo apt-get update
  sudo apt-get install portaudio19-dev libsdl-pango-dev
  

  注：其他 Linux 发行版或 macOS 用户请参考 Manim 官方安装文档 安装对应依赖。

安装步骤

1. 创建并激活 Conda 环境

conda create --name tea python=3.12.8
conda activate tea

2. 安装 Python 依赖

pip install -r requirements.txt

国内用户建议使用清华或阿里镜像源加速安装：

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

3. 下载 TTS 模型 (Kokoro)

下载语音合成所需的模型文件和声音配置文件：

mkdir -p models 
wget -P models https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/kokoro-v0_19.onnx 
wget -P models https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/voices.bin

若下载速度慢，可手动在浏览器下载后放入 models 目录。

4. 配置环境变量

复制模板文件并编辑 .env，填入你所使用的 LLM API Key（支持 OpenAI, Azure, Google Vertex/Gemini 等）：

touch .env

使用文本编辑器打开 .env，参考以下格式填写：

# OpenAI 示例
OPENAI_API_KEY="sk-..."

# Google Gemini 示例
GEMINI_API_KEY="..."

# Kokoro TTS 设置 (通常无需修改，除非路径变动)
KOKORO_MODEL_PATH="models/kokoro-v0_19.onnx"
KOKORO_VOICES_PATH="models/voices.bin"
KOKORO_DEFAULT_VOICE="af"
KOKORO_DEFAULT_SPEED="1.0"
KOKORO_DEFAULT_LANG="en-us"

详细提供商配置请参考 LiteLLM 文档。

5. 配置 Python 路径

为避免导入错误，需将当前项目路径加入 PYTHONPATH：

export PYTHONPATH=$(pwd):$PYTHONPATH

建议将此命令添加到 ~/.bashrc 或 ~/.zshrc 中，或在每次激活环境后执行。

基本使用

生成单个定理视频

使用 generate_video.py 脚本，指定模型、主题和上下文描述即可生成视频。

示例：生成关于“大 O 表示法”的解释视频

python generate_video.py \
      --model "openai/o3-mini" \
      --helper_model "openai/o3-mini" \
      --output_dir "output/my_exp_name" \
      --topic "Big O notation" \
      --context "most common type of asymptotic notation in computer science used to measure worst case complexity"

参数说明

• --model: 主推理模型（遵循 LiteLLM 命名规范，如 openai/gpt-4o, gemini/gemini-1.5-pro）。
• --helper_model: 辅助模型，可用于代码校验或子任务。
• --topic: 定理或知识点的名称。
• --context: 对该主题的简要描述，帮助模型更好地理解背景。
• --output_dir: 视频及中间文件的输出目录。

批量生成（可选）

若需批量处理预定义的定理列表（JSON 格式）：

python generate_video.py \
      --model "openai/o3-mini" \
      --helper_model "openai/o3-mini" \
      --output_dir "output/batch_exp" \
      --theorems_path data/thb_easy/math.json \
      --max_scene_concurrency 7 \
      --max_topic_concurrency 20

提示: 生成过程依赖所选模型的 API 响应速度及本地 GPU/CPU 渲染能力。如遇渲染错误，请检查 LaTeX 及 Manim 依赖是否安装完整。