# IALM

**Repository Path**: tod-research/IALM

## Basic Information

- **Project Name**: IALM
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-02
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IALM: Internal Alignment of Language Models for Explainable Task-Oriented Dialogue

IALM是一个基于Python 3.10的对话系统研究项目，实现了论文实验所需的各项功能，包括对话执行层、策略记忆演化层和用户模拟等功能。项目使用LLM API接口（支持开源和闭源模型），处理MultiWoZ和SGD数据集。

## 项目结构

```
IALM/
├── README.md                # 项目说明文档
├── requirements.txt         # 依赖包列表
├── config/                  # 配置文件目录
│   ├── __init__.py
│   ├── default_config.yaml  # 默认配置
│   ├── model_config.yaml    # 模型配置
│   └── experiment_config.yaml # 实验配置
├── src/                     # 源代码目录
│   ├── __init__.py
│   ├── agents/              # Agent实现
│   │   ├── __init__.py
│   │   ├── base_agent.py    # Agent基类
│   │   ├── dst_agent.py     # DST Agent
│   │   ├── dp_agent.py      # DP Agent
│   │   ├── nlg_agent.py     # NLG Agent
│   │   ├── hsm_evolver.py   # HSM Evolver Agent
│   │   └── user_sim.py      # User Sim Agent
│   ├── memory/              # 记忆系统
│   │   ├── __init__.py
│   │   ├── ssm.py           # 共享结构化记忆
│   │   ├── hsm.py           # 分层策略记忆
│   │   └── retriever.py     # 记忆检索器
│   ├── database/            # 数据库交互
│   │   ├── __init__.py
│   │   ├── db_interface.py  # 数据库接口
│   │   └── db_schema.py     # 数据库模式
│   ├── models/              # 数据模型
│   │   ├── __init__.py
│   │   ├── dialogue.py      # 对话模型
│   │   ├── belief_state.py  # 信念状态模型
│   │   └── strategy.py      # 策略模型
│   ├── utils/               # 工具函数
│   │   ├── __init__.py
│   │   ├── llm_client.py    # LLM客户端
│   │   ├── data_loader.py   # 数据加载器
│   │   ├── data_initializer.py # 对话数据初始化器
│   │   └── metrics.py       # 评估指标
│   └── core/                # 核心组件
│       ├── __init__.py
│       ├── dialogue_manager.py # 对话管理器
│       └── experiment_runner.py # 实验运行器
├── data/                    # 数据目录
│   ├── multiwoz/            # MultiWoZ数据集
│   │   └── data/            # convlab unified格式数据
│   └── sgd/                 # SGD数据集
│       └── data/            # convlab unified格式数据
├── experiments/             # 实验脚本
│   ├── __init__.py
│   ├── run_experiment.py    # 主实验脚本
│   ├── evaluation.py        # 评估脚本
│   └── analysis.py          # 结果分析脚本
├── tests/                   # 测试代码
│   ├── __init__.py
│   ├── test_agents.py       # Agent测试
│   ├── test_memory.py       # 记忆系统测试
│   └── test_utils.py        # 工具函数测试
└── docs/                    # 文档目录
    ├── api.md               # API文档
    └── usage.md             # 使用说明
```

## 功能概述

### Agent系统

项目实现了多种Agent，每种Agent负责对话系统中的特定任务：

1. **BaseAgent**: 所有Agent的基类，定义通用接口和属性
2. **UserSimAgent**: 用户模拟Agent，模拟用户行为和响应
3. **DSTAgent**: 对话状态跟踪Agent，跟踪对话中的信念状态
4. **DPAgent**: 对话策略Agent，决定系统下一步行动
5. **NLGAgent**: 自然语言生成Agent，生成系统响应
6. **HSMEvolver**: 策略记忆演化Agent，管理和演化对话策略

### 记忆系统

记忆系统是IALM的核心组件，负责存储和检索对话相关信息：

1. **SharedStructuredMemory (SSM)**: 共享结构化记忆，存储对话历史和状态
2. **HierarchicalStrategyMemory (HSM)**: 分层策略记忆，存储和管理对话策略
3. **Retriever**: 记忆检索器，根据上下文检索相关记忆和策略

### 核心组件

1. **DialogueManager**: 对话管理器，协调各Agent之间的交互
2. **ExperimentRunner**: 实验运行器，执行实验并收集结果

## 安装与配置

### 环境要求

- Python 3.10+
- 依赖包见requirements.txt

### 安装步骤

1. 克隆项目仓库：
```bash
git clone https://github.com/your-repo/IALM.git
cd IALM
```

2. 创建虚拟环境：
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows
```

3. 安装依赖：
```bash
pip install -r requirements.txt
```

### 配置说明

1. 复制配置文件：
```bash
cp config/default_config.yaml.example config/default_config.yaml
```

2. 编辑配置文件，设置API密钥和其他参数：
```yaml
llm:
  provider: "openai"  # 或其他支持的提供商
  api_key: "your-api-key"
  model: "gpt-3.5-turbo"
```

## 使用方法

### 运行实验

1. 准备数据：
```bash
# 下载并准备MultiWoZ和SGD数据集
python -m src.utils.data_initializer --dataset multiwoz
python -m src.utils.data_initializer --dataset sgd
```

2. 运行实验：
```bash
python experiments/run_experiment.py --config config/experiment_config.yaml
```

3. 评估结果：
```bash
python experiments/evaluation.py --results_path experiments/results/experiment_001
```

### 使用API

```python
from src.core.dialogue_manager import DialogueManager
from src.utils.llm_client import LLMClient

# 初始化LLM客户端
llm_client = LLMClient(config["llm"])

# 初始化对话管理器
dialogue_manager = DialogueManager(config["dialogue_manager"])

# 开始对话
dialogue_id = dialogue_manager.start_dialogue("restaurant")
response = dialogue_manager.process_turn(dialogue_id, "I'm looking for a cheap Italian restaurant")
print(response["system_utterance"])
```

## 数据格式

项目使用ConvLab-3统一格式处理MultiWoZ和SGD数据集：

```json
{
  "dataset": "multiwoz",
  "data_split": "train",
  "dialogue_id": "multiwoz21-train-0",
  "domain": "restaurant",
  "turns": [
    {
      "turn_id": 0,
      "speaker": "user",
      "utterance": "I'm looking for a cheap Italian restaurant",
      "belief_state": {
        "food": "Italian",
        "price": "cheap"
      },
      "system_acts": [],
      "system_response": null
    }
  ]
}
```

## 实验设置

### 基线模型

项目实现了多种基线模型用于比较：

1. **SimpleRule**: 基于规则的简单基线
2. **T5**: 基于T5的端到端模型
3. **GPT-2**: 基于GPT-2的生成模型
4. **DialoGPT**: 基于DialoGPT的对话模型

### 评估指标

使用以下指标评估模型性能：

1. **Inform Rate**: 信息提供率
2. **Success Rate**: 任务成功率
3. **BLEU**: 响应质量
4. **Entity F1**: 实体识别准确率
5. **Response Diversity**: 响应多样性

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

## 许可证

本项目采用MIT许可证 - 详见LICENSE文件

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交Issue: [GitHub Issues](https://github.com/your-repo/IALM/issues)
- 邮箱: your-email@example.com

## 致谢

感谢以下项目和资源的支持：

- [ConvLab-3](https://github.com/ConvLab/ConvLab-3): 对话系统框架
- [MultiWoZ](https://github.com/budzianowski/multiwoz): 多领域对话数据集
- [SGD](https://github.com/google-research-datasets/sgd): Schema-Guided Dialogue数据集