hypogenic

Hypogenic

概述

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

快速开始

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

# Install the package
uv pip install hypogenic

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

# Run basic hypothesis generation
hypogenic_generation --config ./data/your_task/config.yaml --method hypogenic --num_hypotheses 20

# Run inference on generated hypotheses
hypogenic_inference --config ./data/your_task/config.yaml --hypotheses output/hypotheses.json

或者使用 Python API：

from hypogenic import BaseTask

# Create task with your configuration
task = BaseTask(config_path="./data/your_task/config.yaml")

# Generate hypotheses
task.generate_hypotheses(method="hypogenic", num_hypotheses=20)

# Run inference
results = task.inference(hypothesis_bank="./output/hypotheses.json")

何时使用此技能

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

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

主要功能

自动生成假设

• 几分钟内从数据生成 10-20+ 个可检验的假设
• 根据验证表现迭代优化
• 支持基于 API 的模型（OpenAI、Anthropic）和本地 LLM

文献整合

• 通过 PDF 处理从研究论文中提取见解
• 将理论基础与经验模式相结合
• 借助 GROBID 实现系统化的文献到假设工作流

性能优化

• Redis 缓存可降低重复实验的 API 成本
• 并行处理大规模假设测试任务
• 自适应优化重点处理具有挑战性的示例

灵活配置

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

经过验证的成果

• 比少样本基线提升 8.97%
• 比仅使用文献的方法提升 15.75%
• 假设多样性达 80-84%（见解无冗余）
• 人类评估者表示决策能力显著提升

核心能力

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

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

流程：

1. 使用少量数据生成候选假设
2. 根据表现迭代优化假设
3. 用从具有挑战性的示例中生成的新假设替换表现不佳的假设

最适用于： 缺乏现有文献的探索性研究、新数据集中的模式发现

2. HypoRefine：文献与数据整合

通过 Agent 式框架协同整合现有文献与经验数据。

流程：

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

最适用于： 具有成熟理论基础的研究、验证或扩展现有理论

3. Union 方法

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

变体：

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

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

安装

通过 pip 安装：

uv pip install 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/Union 方法）

要使用基于文献的假设生成，你必须预处理 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 用法

如需以编程方式控制并自定义工作流，可直接在 Python 代码中使用 Hypogenic：

基本 HypoGeniC 生成

from hypogenic import BaseTask

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

# Load your task with custom extract_label function
task = BaseTask(
    config_path="./data/your_task/config.yaml",
    extract_label=lambda text: extract_your_label(text)
)

# Generate hypotheses
task.generate_hypotheses(
    method="hypogenic",
    num_hypotheses=20,
    output_path="./output/hypotheses.json"
)

# Run inference
results = task.inference(
    hypothesis_bank="./output/hypotheses.json",
    test_data="./data/your_task/your_task_test.json"
)

HypoRefine/Union 方法

# For literature-integrated approaches
# git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

# Generate with HypoRefine
task.generate_hypotheses(
    method="hyporefine",
    num_hypotheses=15,
    literature_path="./literature/your_task/",
    output_path="./output/"
)
# This generates 3 hypothesis banks:
# - HypoRefine (integrated approach)
# - Literature-only hypotheses
# - Literature∪HypoRefine (union)

多假设推理

from examples.multi_hyp_inference import run_multi_hypothesis_inference

# Test multiple hypotheses simultaneously
results = run_multi_hypothesis_inference(
    config_path="./data/your_task/config.yaml",
    hypothesis_bank="./output/hypotheses.json",
    test_data="./data/your_task/your_task_test.json"
)

自定义标签提取

extract_label() 函数对于解析大模型输出至关重要。请根据你的任务实现此函数：

def extract_label(llm_output: str) -> str:
    """Extract predicted label from LLM inference text.
    
    Default behavior: searches for 'final answer:\s+(.*)' pattern.
    Customize for your domain-specific output format.
    """
    import re
    match = re.search(r'final answer:\s+(.*)', llm_output, re.IGNORECASE)
    if match:
        return match.group(1).strip()
    return llm_output.strip()

重要： 提取的标签必须与数据集中 label 值的格式一致，才能正确计算准确率。

工作流示例

示例 1：数据驱动的假设生成（HypoGeniC）

场景： 在没有先验理论框架的情况下检测 AI 生成的内容

步骤：

1. 准备包含文本样本和标签（人工撰写或 AI 生成）的数据集
2. 创建包含适当提示词模板的 config.yaml
3. 运行假设生成：

   hypogenic_generation --config config.yaml --method hypogenic --num_hypotheses 20
   

4. 在测试集上运行推理：

   hypogenic_inference --config config.yaml --hypotheses output/hypotheses.json --test_data data/test.json
   

5. 分析结果，寻找正式程度、语法准确性和语气差异等模式

示例 2：文献启发的假设检验（HypoRefine）

场景： 在已有研究的基础上检测酒店评论中的欺骗行为

步骤：

1. 收集 10 篇关于语言欺骗线索的相关论文
2. 准备包含真实和虚假评论的数据集
3. 配置 config.yaml，设置文献处理和数据生成模板
4. 运行 HypoRefine：

   hypogenic_generation --config config.yaml --method hyporefine --papers papers/ --num_hypotheses 15
   

5. 测试关于代词频率、细节具体程度和其他语言模式的假设
6. 比较基于文献和数据驱动的假设表现

示例 3：全面覆盖假设（并集方法）

场景： 最大限度提高假设多样性的心理压力检测

步骤：

1. 从心理健康研究论文中生成文献假设
2. 从社交媒体帖子中生成数据驱动假设
3. 运行并集方法进行合并和去重：

   hypogenic_generation --config config.yaml --method union --literature_hypotheses lit_hyp.json
   

4. 推理同时捕捉理论构念（发帖行为变化）和数据模式（情绪语言变化）

性能优化

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

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

自适应优化： 使用具有挑战性的示例，迭代改进假设质量

预期结果

使用 hypogenic 的研究已表明：

• AI 内容检测任务的准确率提高了 14.19%
• 欺骗检测任务的准确率提高了 7.44%
• 80-84% 的假设对能提供不同且不冗余的见解
• 在多个研究领域中，人类评估者给出的有用性评分较高

故障排除

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

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

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

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

创建自定义任务

要向 Hypogenic 添加新任务或数据集：

第 1 步：准备数据集

按照所需格式创建三个 JSON 文件：

• your_task_train.json
• your_task_val.json
• your_task_test.json

每个文件都必须包含文本特征（text_features_1 等）和 label 对应的键。

第 2 步：创建 config.yaml

定义任务配置，包括：

• 任务名称和数据集路径
• 用于观察、生成和推理的提示词模板
• 可复用提示词组件所需的任何额外键
• 占位变量（例如 ${text_features_1}、${num_hypotheses}）

第 3 步：实现 extract_label 函数

创建自定义标签提取函数，以解析特定领域的 LLM 输出：

from hypogenic import BaseTask

def extract_my_label(llm_output: str) -> str:
    """Custom label extraction for your task.
    
    Must return labels in same format as dataset 'label' field.
    """
    # Example: Extract from specific format
    if "Final prediction:" in llm_output:
        return llm_output.split("Final prediction:")[-1].strip()
    
    # Fallback to default pattern
    import re
    match = re.search(r'final answer:\s+(.*)', llm_output, re.IGNORECASE)
    return match.group(1).strip() if match else llm_output.strip()

# Use your custom task
task = BaseTask(
    config_path="./your_task/config.yaml",
    extract_label=extract_my_label
)

第 4 步：（可选）处理文献

对于 HypoRefine/Union 方法：

1. 创建 literature/your_task_name/raw/ 目录
2. 添加相关研究论文 PDF
3. 运行 GROBID 预处理
4. 使用 pdf_preprocess.py 进行处理

第 5 步：生成并测试

使用 CLI 或 Python API 运行假设生成和推理：

# CLI approach
hypogenic_generation --config your_task/config.yaml --method hypogenic --num_hypotheses 20
hypogenic_inference --config your_task/config.yaml --hypotheses output/hypotheses.json

# Or use Python API (see Python API Usage section)

仓库结构

了解仓库布局：

hypothesis-generation/
├── hypogenic/              # Core package code
├── hypogenic_cmd/          # CLI entry points
├── hypothesis_agent/       # HypoRefine agent framework
├── literature/            # Literature processing utilities
├── modules/               # GROBID and preprocessing modules
├── examples/              # Example scripts
│   ├── generation.py      # Basic HypoGeniC generation
│   ├── union_generation.py # HypoRefine/Union generation
│   ├── inference.py       # Single hypothesis inference
│   ├── multi_hyp_inference.py # Multiple hypothesis inference
│   └── pdf_preprocess.py  # Literature PDF processing
├── data/                  # Example datasets (clone separately)
├── tests/                 # Unit tests
└── IO_prompting/          # Prompt templates and experiments

主要目录：

• hypogenic/：包含 BaseTask 和生成逻辑的主包
• examples/：常见工作流的参考实现
• literature/：用于 PDF 处理和文献提取的工具
• modules/：外部工具集成（GROBID 等）

相关出版物

HypoBench（2025）

Liu, H., Huang, S., Hu, J., Zhou, Y., & Tan, C.（2025）。HypoBench：迈向系统且有原则的假设生成基准测试。arXiv 预印本 arXiv:2504.11524。

• 论文： https://arxiv.org/abs/2504.11524
• 简介： 用于系统评估假设生成方法的基准测试框架

BibTeX：

@misc{liu2025hypobenchsystematicprincipledbenchmarking,
      title={HypoBench: Towards Systematic and Principled Benchmarking for Hypothesis Generation}, 
      author={Haokun Liu and Sicong Huang and Jingyu Hu and Yangqiaoyu Zhou and Chenhao Tan},
      year={2025},
      eprint={2504.11524},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2504.11524}, 
}

文献与数据相遇（2024）

Liu, H., Zhou, Y., Li, M., Yuan, C., & Tan, C. (2024). Literature Meets Data: A Synergistic Approach to Hypothesis Generation. arXiv 预印本 arXiv:2410.17309。

• 论文： https://arxiv.org/abs/2410.17309
• 代码： https://github.com/ChicagoHAI/hypothesis-generation
• 描述： 介绍 HypoRefine，并展示基于文献和数据驱动的假设生成方法如何协同结合

BibTeX：

@misc{liu2024literaturemeetsdatasynergistic,
      title={Literature Meets Data: A Synergistic Approach to Hypothesis Generation}, 
      author={Haokun Liu and Yangqiaoyu Zhou and Mingxuan Li and Chenfei Yuan and Chenhao Tan},
      year={2024},
      eprint={2410.17309},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2410.17309}, 
}

使用大语言模型生成假设（2024）

Zhou, Y., Liu, H., Srivastava, T., Mei, H., & Tan, C. (2024). Hypothesis Generation with Large Language Models. 载于 EMNLP Workshop of NLP for Science 论文集。

• 论文： https://aclanthology.org/2024.nlp4science-1.10/
• 描述： 用于数据驱动假设生成的原始 HypoGeniC 框架

BibTeX：

@inproceedings{zhou2024hypothesisgenerationlargelanguage,
      title={Hypothesis Generation with Large Language Models}, 
      author={Yangqiaoyu Zhou and Haokun Liu and Tejes Srivastava and Hongyuan Mei and Chenhao Tan},
      booktitle = {Proceedings of EMNLP Workshop of NLP for Science},
      year={2024},
      url={https://aclanthology.org/2024.nlp4science-1.10/},
}

其他资源

官方链接

• 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

社区与贡献

• 贡献者： 7 位以上活跃贡献者
• 星标： GitHub 上 89 个以上
• 主题： research-tool、interpretability、hypothesis-generation、scientific-discovery、llm-application

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

本地资源

references/

config_template.yaml - 完整的示例配置文件，包含所有必需的提示词模板和参数。其中包括：

• 任务配置的完整 YAML 结构
• 所有方法的示例提示词模板
• 占位变量说明文档
• 基于角色的提示词示例

scripts/

脚本目录可用于：

• 自定义数据准备实用工具
• 格式转换工具
• 分析和评估脚本
• 与外部工具集成

assets/

资源目录可用于：

• 示例数据集和模板
• 假设库样例
• 可视化输出
• 文档补充材料