alterlab-hypogenic

Hypogenic

概述

Hypogenic 使用大语言模型自动生成并检验假设，以加速科学发现。该框架支持三种方法：HypoGeniC（数据驱动的假设生成）、HypoRefine（协同整合文献与数据）和 Union 方法（以机制方式组合文献假设与数据驱动假设）。

快速开始

只需几分钟即可开始使用 Hypogenic：

# Install into its own environment: hypogenic 0.3.5 pins numpy~=1.26, pandas~=2.1,
# torch~=2.4, transformers~=4.45, openai~=1.40 and anthropic~=0.32 (Python 3.10–3.12)
uv venv .venv-hypogenic --python 3.10 && source .venv-hypogenic/bin/activate
uv pip install hypogenic

# Clone example datasets
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# Run data-driven hypothesis generation (model_type: gpt | claude | vllm | huggingface)
hypogenic_generation --task_config_path ./data/your_task/config.yaml \
    --model_type gpt --model_name <provider-model-id> \
    --max_num_hypotheses 20 --output_folder ./outputs/your_task

# Run inference with a saved hypothesis bank
hypogenic_inference --task_config_path ./data/your_task/config.yaml \
    --hypothesis_file ./outputs/your_task/<hypotheses_*.json> \
    --model_type gpt --model_name <provider-model-id>

已根据 hypogenic 0.3.5 的控制台脚本（hypogenic_cmd）验证这些标志。CLI 涵盖数据驱动的 HypoGeniC 生成与推断；HypoRefine 和 Union 运行由示例脚本 驱动（见下文）。运行 --help 查看完整选项列表。

也可以使用示例脚本（该库在 examples/ 下提供可运行脚本；没有单行的流式 task.generate_hypotheses(...) API——真实类请参阅下文的“Python API 用法”）：

python ./examples/generation.py   --help   # HypoGeniC data-driven generation
python ./examples/inference.py     --help   # single-hypothesis inference

何时使用此技能

在以下场景中使用此技能：

• 从观测数据集中生成科学假设
• 系统地检验多个相互竞争的假设
• 将文献见解与经验模式相结合
• 通过自动化假设构思加速研究发现
• 需要基于假设开展分析的领域：欺骗检测、AI 生成内容识别、心理健康指标、预测建模或其他经验研究

不适用的场景

场景	改用
根据观测结果手动构建可证伪的假设和预测（不使用 LLM 流程）	alterlab-hypothesis-gen
尚无数据集的开放式构思或研究空白头脑风暴	alterlab-scientific-brainstorm
将文本主题模型、词典或监督分类器用于社会科学测量	alterlab-text-as-data
使用传统统计检验测试一个预先指定的假设	alterlab-statistical-analysis

主要特性

自动生成假设

• 几分钟内从数据生成 10–20 个以上可检验的假设
• 根据验证性能迭代优化
• 支持基于 API 的模型（OpenAI、Anthropic）和本地大模型

文献整合

• 通过 PDF 处理从研究论文中提取见解
• 将理论基础与经验模式相结合
• 使用 GROBID 构建系统化的文献到假设流程

性能优化

• Redis 缓存可降低重复实验的 API 成本
• 并行处理支持大规模假设检验
• 自适应优化聚焦于具有挑战性的示例

灵活配置

• 基于模板的提示词工程，支持变量注入
• 支持针对特定领域任务自定义标签提取
• 模块化架构，便于扩展

已报告结果（来自 arXiv:2410.17309，文献遇见数据）

• 相较于少样本、仅文献和仅数据驱动基线，分别提升 +8.97%、+15.75% 和 +3.37%
• 人类准确率提升 +7.44%（欺骗检测）和 +14.19%（AI 生成内容检测）
• 冗余检查器会剔除近似重复的假设，确保最终假设库具有多样性

核心能力

1. HypoGeniC：数据驱动的假设生成

通过迭代优化，仅依据观测数据生成假设。

流程：

1. 使用少量数据初始化，生成候选假设
2. 根据性能迭代优化假设
3. 用来自难例的新假设替换表现不佳的假设

最适用于： 缺少现有文献时开展探索性研究，以及在新数据集中发现模式

2. HypoRefine：文献与数据整合

通过 Agent 框架，将现有文献与实证数据协同结合。

流程：

1. 从相关研究论文中提取见解（通常为 10 篇论文）
2. 根据文献生成以理论为基础的假设
3. 根据观察到的模式生成数据驱动的假设
4. 通过迭代改进，完善两个假设库

最适用于： 具有成熟理论基础的研究，以及验证或拓展现有理论

3. 联合方法

以机制化方式，将仅基于文献的假设与框架输出相结合。

变体：

• 文献 ∪ HypoGeniC：将文献假设与数据驱动的生成相结合
• 文献 ∪ HypoRefine：将文献假设与整合方法相结合

最适用于： 全面覆盖假设，在保持视角多样性的同时消除冗余

安装

通过 pip 安装：

uv pip install hypogenic

由于上述依赖项版本已固定，请勿将 hypogenic 安装在主分析环境中。

可选依赖项：

• Redis server（端口 6832）：支持缓存 LLM 响应，从而显著降低迭代生成假设时的 API 成本
• s2orc-doc2json：在 HypoRefine 工作流中处理文献 PDF 时需要
• GROBID：PDF 预处理时需要（参见“文献处理”部分）

克隆示例数据集：

# For HypoGeniC examples
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# For HypoRefine/Union examples
git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

数据集格式

数据集必须遵循 HuggingFace datasets 格式，并使用特定的命名约定：

必需文件：

• <TASK>_train.json：训练数据
• <TASK>_val.json：验证数据
• <TASK>_test.json：测试数据

JSON 中的必需键：

• text_features_1 到 text_features_n：包含特征值的字符串列表
• label：包含真实标签的字符串列表

示例（标题点击预测）：

{
  "headline_1": [
    "What Up, Comet? You Just Got *PROBED*",
    "Scientists Made a Breakthrough in Quantum Computing"
  ],
  "headline_2": [
    "Scientists Everywhere Were Holding Their Breath Today. Here's Why.",
    "New Quantum Computer Achieves Milestone"
  ],
  "label": [
    "Headline 2 has more clicks than Headline 1",
    "Headline 1 has more clicks than Headline 2"
  ]
}

重要说明：

• 所有列表的长度必须相同
• 标签格式必须与 extract_label() 函数的输出格式一致
• 可自定义特征键以匹配您的领域（例如，review_text、post_content 等）

配置

每项任务都需要一个 config.yaml 文件，其中指定：

必需元素：

• 数据集路径（train/val/test）
• 以下内容的提示词模板：
  • 观察结果生成
  • 批量假设生成
  • 假设推理
  • 相关性检查
  • 自适应方法（用于 HypoRefine）

模板功能：

• 用于动态注入变量的数据集占位符（例如，${text_features_1}、${num_hypotheses}）
• 用于领域特定解析的自定义标签提取函数
• 基于角色的提示词结构（system、user、assistant 角色）

配置结构：

task_name: your_task_name

train_data_path: ./your_task_train.json
val_data_path: ./your_task_val.json
test_data_path: ./your_task_test.json

prompt_templates:
  # Extra keys for reusable prompt components
  observations: |
    Feature 1: ${text_features_1}
    Feature 2: ${text_features_2}
    Observation: ${label}
  
  # Required templates
  batched_generation:
    system: "Your system prompt here"
    user: "Your user prompt with ${num_hypotheses} placeholder"
  
  inference:
    system: "Your inference system prompt"
    user: "Your inference user prompt"
  
  # Optional templates for advanced features
  few_shot_baseline: {...}
  is_relevant: {...}
  adaptive_inference: {...}
  adaptive_selection: {...}

完整配置示例请参阅 references/config_template.yaml。

文献处理（HypoRefine/联合方法）

若要使用基于文献的假设生成，必须预处理论文 PDF：

步骤 1：设置 GROBID（仅首次需要）

bash ./modules/setup_grobid.sh

步骤 2：添加 PDF 文件 将研究论文放入 literature/YOUR_TASK_NAME/raw/

步骤 3：处理 PDF

# Start GROBID service
bash ./modules/run_grobid.sh

# Process PDFs for your task
cd examples
python pdf_preprocess.py --task_name YOUR_TASK_NAME

此操作会将 PDF 转换为结构化格式，以便提取假设。未来版本将支持自动文献搜索。

CLI 用法

假设生成

hypogenic_generation --help

主要参数：

• 任务配置文件路径
• 模型选择（基于 API 或本地）
• 生成方法（HypoGeniC、HypoRefine 或 Union）
• 要生成的假设数量
• 假设库的输出目录

假设推理

hypogenic_inference --help

主要参数：

• 任务配置文件路径
• 假设库文件路径
• 测试数据集路径
• 推理方法（默认或多假设）
• 结果输出文件

Python API 用法

该库不是一次调用即可使用的流畅 API——生成过程以显式的初始化／更新循环运行，涉及算法类（DefaultGeneration、DefaultInference、DefaultUpdate、DefaultReplace）；推理则通过 inference_register 执行。复制并改编 examples/ 下的脚本；对于 HypoRefine/Union，请改编 examples/union_generation.py。

完整导入列表、生成／推理循环、inference_type 策略选项，以及关键的 extract_label() 解析约定，请参阅 references/python_api.md。

工作流示例

三个端到端场景——数据驱动（HypoGeniC、AI 内容检测）、结合文献（HypoRefine、酒店评论中的欺骗）和全面覆盖（Union、心理压力检测）——每个场景都包含数据集准备、生成和推理命令。请参阅 references/workflow_examples.md。

性能优化

**缓存：**启用 Redis 缓存，降低重复 LLM 调用的 API 成本和计算时间

**并行处理：**利用多个工作进程，大规模生成和测试假设

**自适应优化：**利用具有挑战性的示例迭代提升假设质量

故障排除

**问题：**生成的假设过于笼统 **解决方案：**优化 config.yaml 中的提示词模板，要求生成更具体、可测试的假设

**问题：**推理效果不佳 **解决方案：**确保数据集包含足够的训练示例，调整假设生成参数，或增加假设数量

**问题：**标签提取失败 **解决方案：**针对特定领域的输出解析，实现自定义 extract_label() 函数

**问题：**GROBID PDF 处理失败 **解决方案：**确保 GROBID 服务正在运行（bash ./modules/run_grobid.sh），且 PDF 是有效的研究论文

创建自定义任务

添加新任务分为五个步骤：（1）准备包含 text_features_* 和 label 键的 train/val/test JSON；（2）编写 config.yaml；（3）实现自定义 extract_label()；（4）可选：为 HypoRefine/Union 处理文献 PDF；（5）运行生成和推理。

完整的分步指南，包含自定义 extract_label 实现和 BaseTask 配置方法，请参阅 references/custom_tasks.md。

仓库结构

核心代码位于 hypogenic/，CLI 入口位于 hypogenic_cmd/，HypoRefine Agent 位于 hypothesis_agent/，PDF／文献工具位于 literature/ 和 modules/，可运行脚本位于 examples/。带注释的完整目录树请参阅 references/repository_structure.md。

相关出版物

该框架基于 ChicagoHAI 的三篇论文：HypoBench（2025，arXiv:2504.11524）、Literature Meets Data（2024，arXiv:2410.17309，介绍 HypoRefine），以及最初的 Hypothesis Generation with Large Language Models（2024，EMNLP NLP4Science）。完整引文、描述和 BibTeX 条目请参阅 references/publications.md。

其他资源

官方链接

• GitHub 仓库： https://github.com/ChicagoHAI/hypothesis-generation
• PyPI 软件包： https://pypi.org/project/hypogenic/
• 许可证： MIT License
• 问题与支持： https://github.com/ChicagoHAI/hypothesis-generation/issues

示例数据集

克隆以下仓库，获取可直接使用的示例：

# HypoGeniC examples (data-driven only)
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# HypoRefine/Union examples (literature + data)
git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

如需贡献或提问，请访问 GitHub 仓库并查看问题页面。

本地资源

references/

• config_template.yaml — 提供可运行形式的 config.yaml，与实际的 hypogenic 架构相匹配（task_name、train/val/test_data_path、包含基于角色的 system/user 子键和 ${...} 占位符的 prompt_templates）。编写配置前请先阅读： 其中说明了 ${...} 替换、可复用的“额外键”机制，以及哪些设置应通过 CLI 标志而非 YAML 配置。
• python_api.md — 初始化/更新生成循环、推理注册表、inference_type 策略选项，以及 extract_label() 解析约定。
• workflow_examples.md — 三个端到端场景（HypoGeniC、HypoRefine、Union）。
• custom_tasks.md — 添加新任务或数据集的五步指南。
• repository_structure.md — 上游代码库的注释版布局。
• publications.md — HypoGeniC/HypoRefine/HypoBench 论文的完整引文和 BibTeX。

属于 AlterLab Academic Skills 套件。