A Simple and Universal Swarm Intelligence Engine, Predicting Anything. 简洁通用的群体智能引擎,预测万物
Python agent-memoryfinancial-forecastingfuture-predictionknowledge-graphllmsmulti-agent-simulationpublic-opinion-analysispython3social-predictionswarm-intelligence
Update README.md for MiroFish Backend with detailed technical documentation
666ghj2333121a4469
diff --git a/backend/README.md b/backend/README.mdindex e620370e..9130b2d3 100644--- a/backend/README.md+++ b/backend/README.md@@ -1,1838 +1,1687 @@-# MiroFish Backend+# MiroFish Backend - 详细技术文档++## 目录++- [项目简介](#项目简介)+- [技术架构](#技术架构)+- [技术栈](#技术栈)+- [项目结构](#项目结构)+- [核心功能模块](#核心功能模块)+- [API接口文档](#api接口文档)+- [数据模型](#数据模型)+- [服务层详解](#服务层详解)+- [工具类](#工具类)+- [配置说明](#配置说明)+- [运行指南](#运行指南)+- [开发指南](#开发指南)+- [常见问题](#常见问题)-社会舆论模拟系统后端服务,基于Flask框架。--## 项目结构+----```-backend/-├── app/-│ ├── __init__.py # Flask应用工厂-│ ├── config.py # 配置管理-│ ├── api/ # API路由-│ │ ├── __init__.py # Blueprint注册-│ │ ├── graph.py # Step1: 图谱相关接口-│ │ └── simulation.py # Step2: 模拟相关接口-│ ├── services/ # 业务逻辑层-│ │ ├── __init__.py # 服务模块导出-│ │ ├── ontology_generator.py # 本体生成服务-│ │ ├── graph_builder.py # 图谱构建服务-│ │ ├── text_processor.py # 文本处理服务-│ │ ├── zep_entity_reader.py # Zep实体读取与过滤-│ │ ├── oasis_profile_generator.py # Agent Profile生成器-│ │ ├── simulation_config_generator.py # LLM智能配置生成器(核心)-│ │ └── simulation_manager.py # 模拟管理器-│ ├── models/ # 数据模型-│ │ ├── task.py # 任务状态管理-│ │ └── project.py # 项目上下文管理-│ └── utils/ # 工具模块-│ ├── file_parser.py # 文件解析-│ ├── llm_client.py # LLM客户端-│ └── logger.py # 日志工具-├── scripts/ # 预设模拟脚本-│ ├── run_twitter_simulation.py # Twitter模拟脚本-│ ├── run_reddit_simulation.py # Reddit模拟脚本-│ └── run_parallel_simulation.py # 双平台并行脚本-├── uploads/ # 上传文件存储-│ ├── projects/ # 项目文件-│ └── simulations/ # 模拟数据(含配置和脚本副本)-├── requirements.txt-└── run.py # 启动入口-```+## 项目简介-## 安装+**MiroFish Backend** 是一个基于 Flask 的后端服务,用于社交媒体舆论模拟。系统核心功能包括:-```bash-conda activate MiroFish-cd backend-pip install -r requirements.txt-```+1. **知识图谱构建**: 从文档中提取实体和关系,使用 Zep Cloud 构建知识图谱+2. **本体生成**: 使用 LLM 自动分析文档并生成适合舆论模拟的实体类型和关系类型+3. **Agent人设生成**: 基于图谱实体,使用 LLM 生成详细的社交媒体用户人设+4. **模拟配置智能生成**: 使用 LLM 根据需求自动生成模拟参数(时间、活跃度、事件等)+5. **双平台模拟**: 支持 Twitter 和 Reddit 双平台并行舆论模拟(基于 OASIS 框架)-## 配置+----在项目根目录 `MiroFish/.env` 中配置:+## 技术架构++```+┌─────────────────────────────────────────────────────────────┐+│ MiroFish Backend │+├─────────────────────────────────────────────────────────────┤+│ Flask Web Framework + CORS │+│ ┌────────────────┐ ┌──────────────┐ ┌─────────────────┐ │+│ │ API层 │ │ 服务层 │ │ 模型层 │ │+│ │ - graph.py │→ │ - 本体生成 │→ │ - Project │ │+│ │ - simulation │ │ - 图谱构建 │ │ - Task │ │+│ └────────────────┘ │ - 实体读取 │ └─────────────────┘ │+│ │ - 人设生成 │ │+│ │ - 配置生成 │ │+│ │ - 模拟运行 │ │+│ └──────────────┘ │+├─────────────────────────────────────────────────────────────┤+│ 外部服务集成 │+│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │+│ │ Zep Cloud│ │ LLM API │ │ OASIS │ │ 文件系统│ │+│ │ 知识图谱 │ │ (OpenAI) │ │ 社交模拟│ │ 存储 │ │+│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │+└─────────────────────────────────────────────────────────────┘+```++### 核心流程++1. **图谱构建流程**:+ ```+ 上传文档 → 提取文本 → LLM生成本体 → 文本分块 → Zep构建图谱+ ```++2. **模拟准备流程**:+ ```+ 创建模拟 → 读取图谱实体 → LLM生成人设 → LLM生成配置 → 准备完成+ ```++3. **模拟运行流程**:+ ```+ 启动模拟 → 运行OASIS脚本 → 实时监控 → 记录动作 → 状态查询+ ```-```bash-# LLM配置(统一使用OpenAI格式)-LLM_API_KEY=your-llm-api-key-LLM_BASE_URL=https://openrouter.ai/api/v1-LLM_MODEL_NAME=gpt-4o-mini+----# Zep配置-ZEP_API_KEY=your-zep-api-key+## 技术栈-# OASIS模拟配置(可选)-OASIS_DEFAULT_MAX_ROUNDS=10-```+### 核心框架+- **Flask 3.0+**: Web 框架+- **Flask-CORS**: 跨域支持-## 启动服务+### AI & 知识图谱+- **Zep Cloud SDK 2.0+**: 知识图谱构建与管理+- **OpenAI SDK 1.0+**: LLM 调用(支持 OpenAI 兼容接口)+- **OASIS-AI**: 社交媒体模拟框架+- **CAMEL-AI**: Agent 行为模拟-```bash-python run.py-```+### 数据处理+- **PyMuPDF (fitz)**: PDF 文本提取+- **Pydantic 2.0+**: 数据验证+- **Python-dotenv**: 环境变量管理-服务默认运行在 http://localhost:5001+### 文件处理+- **Werkzeug 3.0+**: 文件上传处理----# 系统架构--## 完整工作流程+## 项目结构```-┌─────────────────────────────────────────────────────────────────────────┐-│ Step 1: 图谱构建 │-├─────────────────────────────────────────────────────────────────────────┤-│ │-│ 上传文档 ──→ 生成本体定义 ──→ 构建Zep图谱 ──→ 图谱数据 │-│ (PDF/MD/TXT) (LLM分析) (异步任务) (节点/边) │-│ │-└─────────────────────────────────────────────────────────────────────────┘- │- ▼-┌─────────────────────────────────────────────────────────────────────────┐-│ Step 2: 实体读取与模拟准备 │-├─────────────────────────────────────────────────────────────────────────┤-│ │-│ 读取图谱节点 ──→ 过滤符合条件实体 ──→ 生成Agent Profile ──→ 生成脚本 │-│ (Zep API) (按Labels筛选) (LLM生成人设) (OASIS启动) │-│ │-└─────────────────────────────────────────────────────────────────────────┘- │- ▼-┌─────────────────────────────────────────────────────────────────────────┐-│ Step 3: 双平台并行模拟 │-├─────────────────────────────────────────────────────────────────────────┤-│ │-│ ┌─────────────────┐ ┌─────────────────┐ │-│ │ Twitter模拟 │ │ Reddit模拟 │ │-│ │ (短平快交互) │ 并行运行 │ (深度话题讨论) │ │-│ └─────────────────┘ └─────────────────┘ │-│ │ │-│ ▼ │-│ 同一批智能体,模拟真实社交环境 │-│ │-└─────────────────────────────────────────────────────────────────────────┘+backend/+├── run.py # 启动入口+├── requirements.txt # Python依赖+├── .env # 环境配置(需创建)+├── logs/ # 日志文件+│ └── YYYY-MM-DD.log+├── uploads/ # 数据存储+│ ├── projects/ # 项目数据+│ │ └── proj_xxx/+│ │ ├── project.json # 项目元数据+│ │ ├── files/ # 上传的文件+│ │ └── extracted_text.txt # 提取的文本+│ └── simulations/ # 模拟数据+│ └── sim_xxx/+│ ├── state.json # 模拟状态+│ ├── simulation_config.json # 模拟配置+│ ├── reddit_profiles.json # Reddit人设+│ ├── twitter_profiles.csv # Twitter人设+│ ├── run_state.json # 运行状态+│ ├── simulation.log # 主日志+│ ├── twitter/ # Twitter数据+│ │ ├── actions.jsonl+│ │ └── twitter_simulation.db+│ └── reddit/ # Reddit数据+│ ├── actions.jsonl+│ └── reddit_simulation.db+├── scripts/ # 模拟运行脚本+│ ├── run_twitter_simulation.py+│ ├── run_reddit_simulation.py+│ ├── run_parallel_simulation.py+│ └── action_logger.py+└── app/+ ├── __init__.py # Flask应用工厂+ ├── config.py # 配置管理+ ├── api/ # API路由+ │ ├── __init__.py+ │ ├── graph.py # 图谱相关接口+ │ └── simulation.py # 模拟相关接口+ ├── models/ # 数据模型+ │ ├── __init__.py+ │ ├── project.py # 项目模型+ │ └── task.py # 任务模型+ ├── services/ # 业务服务+ │ ├── __init__.py+ │ ├── ontology_generator.py # 本体生成+ │ ├── graph_builder.py # 图谱构建+ │ ├── text_processor.py # 文本处理+ │ ├── zep_entity_reader.py # 实体读取+ │ ├── oasis_profile_generator.py # 人设生成+ │ ├── simulation_config_generator.py # 配置生成+ │ ├── simulation_manager.py # 模拟管理+ │ └── simulation_runner.py # 模拟运行+ └── utils/ # 工具类+ ├── __init__.py+ ├── file_parser.py # 文件解析+ ├── llm_client.py # LLM客户端+ ├── logger.py # 日志配置+ └── retry.py # 重试机制```----# Step 1: 图谱构建 API+## 核心功能模块-## 核心工作流程+### 1. 图谱构建模块-```-1. 上传文件 + 生成本体- POST /api/graph/ontology/generate- → 返回 project_id--2. 构建图谱- POST /api/graph/build- → 返回 task_id--3. 查询任务进度- GET /api/graph/task/{task_id}--4. 获取图谱数据- GET /api/graph/data/{graph_id}-```+**功能**: 从文档构建知识图谱++**流程**:+1. 上传文档(PDF/TXT/MD)+2. 提取文本内容+3. LLM分析生成本体(实体类型+关系类型)+4. 文本分块(chunk_size=500, overlap=50)+5. 调用 Zep API 构建图谱+6. 等待 Zep 处理完成+7. 返回图谱ID和统计信息++**核心服务**:+- `OntologyGenerator`: 本体生成+- `GraphBuilderService`: 图谱构建+- `TextProcessor`: 文本处理++### 2. 模拟准备模块++**功能**: 准备舆论模拟所需的所有数据++**流程**:+1. 创建模拟(指定project_id和graph_id)+2. 从 Zep 图谱读取并过滤实体+3. 为每个实体生成 OASIS Agent Profile(支持并行)+4. 使用 LLM 智能生成模拟配置(时间/活跃度/事件)+5. 保存配置文件和人设文件++**核心服务**:+- `ZepEntityReader`: 实体读取与过滤+- `OasisProfileGenerator`: Agent人设生成+- `SimulationConfigGenerator`: 模拟配置生成+- `SimulationManager`: 模拟管理++### 3. 模拟运行模块++**功能**: 运行 Twitter/Reddit 双平台舆论模拟++**流程**:+1. 检查模拟准备状态+2. 启动 OASIS 模拟进程(subprocess)+3. 监控进程运行状态+4. 解析动作日志(actions.jsonl)+5. 实时更新运行状态+6. 支持停止/暂停/恢复++**核心服务**:+- `SimulationRunner`: 模拟运行器----### 接口1:生成本体定义+## API接口文档++### 图谱管理接口-**POST** `/api/graph/ontology/generate`+#### 1. 生成本体-上传文档,分析生成适合社会模拟的实体和关系类型定义。+**接口**: `POST /api/graph/ontology/generate`-**请求(form-data):**+**请求类型**: `multipart/form-data`-| 字段 | 类型 | 必填 | 说明 |+**请求参数**:+| 参数 | 类型 | 必填 | 说明 ||------|------|------|------|-| `files` | File | 是 | PDF/MD/TXT文件,可多个 |-| `simulation_requirement` | Text | 是 | 模拟需求描述 |-| `project_name` | Text | 否 | 项目名称 |-| `additional_context` | Text | 否 | 额外说明 |+| files | File[] | 是 | 上传的文档(PDF/MD/TXT) |+| simulation_requirement | String | 是 | 模拟需求描述 |+| project_name | String | 否 | 项目名称 |+| additional_context | String | 否 | 额外说明 |-**响应示例:**+**返回示例**:```json{- "success": true,- "data": {- "project_id": "proj_abc123def456",- "project_name": "武汉大学舆情分析",- "ontology": {- "entity_types": [- {- "name": "Student",- "description": "Students enrolled in educational institutions",- "attributes": [- {"name": "student_id", "type": "text", "description": "Unique identifier"},- {"name": "major", "type": "text", "description": "Field of study"}- ]- }- ],- "edge_types": [- {- "name": "AFFILIATED_WITH",- "description": "Indicates affiliation between entities",- "source_targets": [- {"source": "Student", "target": "University"}- ]- }- ]+ "success": true,+ "data": {+ "project_id": "proj_33469c670f56",+ "project_name": "学术不端事件模拟",+ "ontology": {+ "entity_types": [+ {+ "name": "Student",+ "description": "Students involved in the event",+ "attributes": [+ {"name": "full_name", "type": "text", "description": "Student full name"},+ {"name": "major", "type": "text", "description": "Major field"}+ ],+ "examples": ["张三", "李四"]},- "analysis_summary": "分析说明...",- "files": [{"filename": "报告.pdf", "size": 123456}],- "total_text_length": 20833- }+ {+ "name": "Professor",+ "description": "Faculty members",+ "attributes": [...]+ },+ ...+ {+ "name": "Person",+ "description": "Any individual person not fitting other specific person types",+ "attributes": [...]+ },+ {+ "name": "Organization",+ "description": "Any organization not fitting other specific types",+ "attributes": [...]+ }+ ],+ "edge_types": [+ {+ "name": "STUDIES_AT",+ "description": "Student studies at university",+ "source_targets": [+ {"source": "Student", "target": "University"}+ ],+ "attributes": []+ },+ ...+ ]+ },+ "analysis_summary": "文档涉及学术不端事件...",+ "files": [+ {"filename": "document.pdf", "size": 102400}+ ],+ "total_text_length": 12345+ }}```+**说明**:+- 本体设计必须包含10个实体类型,最后2个为兜底类型(`Person`和`Organization`)+- 实体类型必须是现实中可以发声的主体+- 属性名不能使用保留字(`name`, `uuid`, `group_id`, `created_at`, `summary`)+----### 接口2:构建图谱+#### 2. 构建图谱-**POST** `/api/graph/build`+**接口**: `POST /api/graph/build`-根据 `project_id` 构建Zep知识图谱(异步任务)。+**请求类型**: `application/json`-**请求(JSON):**+**请求参数**:```json{- "project_id": "proj_abc123def456",- "graph_name": "图谱名称",- "chunk_size": 500,- "chunk_overlap": 50+ "project_id": "proj_33469c670f56",+ "graph_name": "学术不端事件图谱",+ "chunk_size": 500,+ "chunk_overlap": 50,+ "force": false}```-| 字段 | 类型 | 必填 | 说明 |-|------|------|------|------|-| `project_id` | string | 是 | 来自接口1的返回 |-| `graph_name` | string | 否 | 图谱名称 |-| `chunk_size` | int | 否 | 文本块大小,默认500 |-| `chunk_overlap` | int | 否 | 块重叠字符,默认50 |+| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| project_id | String | 是 | - | 项目ID(来自接口1) |+| graph_name | String | 否 | 项目名称 | 图谱名称 |+| chunk_size | Integer | 否 | 500 | 文本块大小 |+| chunk_overlap | Integer | 否 | 50 | 块重叠大小 |+| force | Boolean | 否 | false | 强制重新构建 |-**响应:**+**返回示例**:```json{- "success": true,- "data": {- "project_id": "proj_abc123def456",- "task_id": "task_xyz789",- "message": "图谱构建任务已启动"- }+ "success": true,+ "data": {+ "project_id": "proj_33469c670f56",+ "task_id": "a1b2c3d4-e5f6-...",+ "message": "图谱构建任务已启动,请通过 /task/{task_id} 查询进度"+ }}```+**异步任务**: 此接口立即返回task_id,实际构建在后台进行+----### 任务状态查询+#### 3. 查询任务状态-**GET** `/api/graph/task/{task_id}`+**接口**: `GET /api/graph/task/{task_id}`+**返回示例**:```json{- "success": true,- "data": {- "task_id": "task_xyz789",- "status": "processing",- "progress": 45,- "message": "Zep处理中... 15/30 完成",- "result": null+ "success": true,+ "data": {+ "task_id": "a1b2c3d4-e5f6-...",+ "task_type": "graph_build",+ "status": "processing",+ "created_at": "2025-12-02T10:00:00",+ "updated_at": "2025-12-02T10:05:00",+ "progress": 45,+ "message": "Zep处理中... 10/30 完成",+ "result": null,+ "error": null,+ "metadata": {+ "project_id": "proj_33469c670f56"}+ }}```-**状态值:**-- `pending` - 等待中-- `processing` - 处理中-- `completed` - 已完成-- `failed` - 失败-------### 项目管理接口--| 方法 | 路径 | 说明 |-|------|------|------|-| GET | `/api/graph/project/{project_id}` | 获取项目详情 |-| GET | `/api/graph/project/list` | 列出所有项目 |-| DELETE | `/api/graph/project/{project_id}` | 删除项目 |-------### 图谱数据接口--| 方法 | 路径 | 说明 |-|------|------|------|-| GET | `/api/graph/data/{graph_id}` | 获取图谱节点和边 |-| DELETE | `/api/graph/delete/{graph_id}` | 删除Zep图谱 |-------# Step 2: 实体读取与模拟运行 API--## 核心设计理念--**全程自动化,无需人工设置参数:**-- 脚本是**预设的**,不是动态生成-- 所有模拟参数由**LLM智能生成**-- LLM读取模拟需求+文档+图谱信息,自动设置最佳参数-- **通过API接口启动和监控模拟**,前端可实时展示--## 核心工作流程--```-1. 创建模拟- POST /api/simulation/create- → 返回 simulation_id--2. 准备模拟环境(异步任务)- POST /api/simulation/prepare- Body: { "simulation_id": "sim_xxxx" }- → 返回 task_id(立即响应)-- 查询进度:- POST /api/simulation/prepare/status- Body: { "task_id": "task_xxxx" }- → 返回 status, progress, result--3. 开始模拟- POST /api/simulation/start- Body: { "simulation_id": "sim_xxxx", "platform": "parallel" }- → 在后台启动OASIS模拟进程- → 返回运行状态--4. 实时监控(前端轮询)- GET /api/simulation/{simulation_id}/run-status/detail- → 返回当前进度、最近Agent动作--5. 停止模拟(可选)- POST /api/simulation/stop- Body: { "simulation_id": "sim_xxxx" }-```+**状态值**:+- `pending`: 等待中+- `processing`: 处理中+- `completed`: 已完成+- `failed`: 失败----## 实体读取接口--### 获取图谱实体(已过滤)--**GET** `/api/simulation/entities/{graph_id}`+#### 4. 获取图谱数据-获取图谱中符合预定义实体类型的节点。--**实体过滤逻辑:**-- Zep对符合预定义类型的实体,Labels为 `["Entity", "Student"]`-- 对不符合预定义类型的实体,Labels仅为 `["Entity"]`-- **筛选规则**:只保留Labels中包含除"Entity"和"Node"之外标签的节点--**Query参数:**--| 参数 | 类型 | 必填 | 说明 |-|------|------|------|------|-| `entity_types` | string | 否 | 逗号分隔的实体类型,用于进一步过滤 |-| `enrich` | boolean | 否 | 是否获取相关边信息,默认true |+**接口**: `GET /api/graph/data/{graph_id}`-**响应示例:**+**返回示例**:```json{- "success": true,- "data": {- "entities": [- {- "uuid": "node_uuid_123",- "name": "杨景媛",- "labels": ["Entity", "Student"],- "summary": "武汉大学学生,图书馆事件当事人",- "attributes": {- "student_id": "2021001",- "major": "计算机科学"- },- "related_edges": [- {- "direction": "outgoing",- "edge_name": "AFFILIATED_WITH",- "fact": "杨景媛是武汉大学的学生",- "target_node_uuid": "node_uuid_456"- }- ],- "related_nodes": [- {- "uuid": "node_uuid_456",- "name": "武汉大学",- "labels": ["Entity", "University"],- "summary": "中国著名高等学府"- }- ]- }- ],- "entity_types": ["Student", "University", "PublicFigure"],- "total_count": 100,- "filtered_count": 45- }+ "success": true,+ "data": {+ "graph_id": "mirofish_abc123",+ "nodes": [+ {+ "uuid": "node-uuid-1",+ "name": "张三",+ "labels": ["Entity", "Student"],+ "summary": "某大学计算机专业学生",+ "attributes": {+ "full_name": "张三",+ "major": "计算机科学"+ }+ },+ ...+ ],+ "edges": [+ {+ "uuid": "edge-uuid-1",+ "name": "STUDIES_AT",+ "fact": "张三就读于某大学",+ "source_node_uuid": "node-uuid-1",+ "target_node_uuid": "node-uuid-2",+ "attributes": {}+ },+ ...+ ],+ "node_count": 50,+ "edge_count": 120+ }}```----### 获取单个实体详情--**GET** `/api/simulation/entities/{graph_id}/{entity_uuid}`+#### 5. 项目管理接口-获取单个实体的完整信息,包含所有相关边和关联节点。+**获取项目**: `GET /api/graph/project/{project_id}`----+**列出项目**: `GET /api/graph/project/list?limit=50`-### 按类型获取实体+**删除项目**: `DELETE /api/graph/project/{project_id}`-**GET** `/api/simulation/entities/{graph_id}/by-type/{entity_type}`--获取指定类型(如Student、PublicFigure)的所有实体。+**重置项目**: `POST /api/graph/project/{project_id}/reset`----## 模拟管理接口+### 模拟管理接口-### 创建模拟+#### 1. 创建模拟-**POST** `/api/simulation/create`+**接口**: `POST /api/simulation/create`-**请求(JSON):**+**请求参数**:```json{- "project_id": "proj_abc123def456",- "graph_id": "mirofish_xxxx",- "enable_twitter": true,- "enable_reddit": true,- "max_rounds": 10,- "agents_per_round": -1+ "project_id": "proj_33469c670f56",+ "graph_id": "mirofish_abc123",+ "enable_twitter": true,+ "enable_reddit": true}```-| 字段 | 类型 | 必填 | 说明 |-|------|------|------|------|-| `project_id` | string | 是 | 项目ID |-| `graph_id` | string | 否 | 图谱ID,不提供则从project获取 |-| `enable_twitter` | boolean | 否 | 启用Twitter模拟,默认true |-| `enable_reddit` | boolean | 否 | 启用Reddit模拟,默认true |-| `max_rounds` | int | 否 | 最大模拟轮数,默认10 |-| `agents_per_round` | int | 否 | 每轮激活智能体数,-1表示全部 |--**响应示例:**+**返回示例**:```json{- "success": true,- "data": {- "simulation_id": "sim_abc123def456",- "config": {- "project_id": "proj_xxxx",- "graph_id": "mirofish_xxxx",- "enable_twitter": true,- "enable_reddit": true,- "max_rounds": 10- },- "status": "created",- "created_at": "2025-12-01T10:00:00"- }+ "success": true,+ "data": {+ "simulation_id": "sim_10b494550540",+ "project_id": "proj_33469c670f56",+ "graph_id": "mirofish_abc123",+ "status": "created",+ "enable_twitter": true,+ "enable_reddit": true,+ "created_at": "2025-12-02T10:00:00"+ }}```----### 准备模拟环境(异步任务)--**POST** `/api/simulation/prepare`--**异步接口**:这是一个耗时操作,接口会立即返回`task_id`,通过`/prepare/status`查询进度。+#### 2. 准备模拟-执行模拟准备流程(LLM智能生成所有参数,带自动重试机制):-1. 从Zep图谱读取并过滤实体-2. 为每个实体生成OASIS Agent Profile(带重试)-3. LLM智能生成模拟配置(带重试)-4. 保存配置文件和复制预设脚本+**接口**: `POST /api/simulation/prepare`-**请求(JSON):**+**请求参数**:```json{- "simulation_id": "sim_xxxx",- "entity_types": ["Student", "PublicFigure"],- "use_llm_for_profiles": true+ "simulation_id": "sim_10b494550540",+ "entity_types": ["Student", "Professor"],+ "use_llm_for_profiles": true,+ "parallel_profile_count": 5,+ "force_regenerate": false}```-**响应示例:**+| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| simulation_id | String | 是 | - | 模拟ID |+| entity_types | String[] | 否 | null | 指定实体类型(为空则全部) |+| use_llm_for_profiles | Boolean | 否 | true | 是否用LLM生成详细人设 |+| parallel_profile_count | Integer | 否 | 5 | 并行生成人设数量 |+| force_regenerate | Boolean | 否 | false | 强制重新生成 |++**返回示例**:```json{- "success": true,- "data": {- "simulation_id": "sim_xxxx",- "task_id": "task_xxxx",- "status": "preparing",- "message": "准备任务已启动,请通过 /api/simulation/prepare/status 查询进度"- }+ "success": true,+ "data": {+ "simulation_id": "sim_10b494550540",+ "task_id": "task_xyz789",+ "status": "preparing",+ "message": "准备任务已启动",+ "already_prepared": false+ }}```----+**特性**:+- 自动检测已完成的准备工作,避免重复生成+- 支持并行生成人设(默认5个并发)+- 支持强制重新生成-### 查询准备进度+----**POST** `/api/simulation/prepare/status`+#### 3. 查询准备进度-查询准备任务的执行进度。+**接口**: `POST /api/simulation/prepare/status`-**请求(JSON):**+**请求参数**:```json{- "task_id": "task_xxxx"+ "task_id": "task_xyz789",+ "simulation_id": "sim_10b494550540"}```-**响应示例:**+**返回示例**:```json{- "success": true,- "data": {- "task_id": "task_xxxx",- "task_type": "simulation_prepare",- "status": "processing",- "progress": 45,- "message": "[2/4] 生成Agent人设: 35/93 - 生成 教授张三 的人设...",- "progress_detail": {- "current_stage": "generating_profiles",- "current_stage_name": "生成Agent人设",- "stage_index": 2,- "total_stages": 4,- "stage_progress": 38,- "current_item": 35,- "total_items": 93,- "item_description": "生成 教授张三 的人设..."- },- "result": null,- "error": null,- "metadata": {- "project_id": "proj_xxxx",- "simulation_id": "sim_xxxx"- }- }+ "success": true,+ "data": {+ "task_id": "task_xyz789",+ "status": "processing",+ "progress": 45,+ "message": "[2/4] 生成Agent配置: 5/15 - 已完成 Student: 张三",+ "progress_detail": {+ "current_stage": "generating_profiles",+ "current_stage_name": "生成Agent人设",+ "stage_index": 2,+ "total_stages": 4,+ "stage_progress": 33,+ "current_item": 5,+ "total_items": 15,+ "item_description": "已完成 Student: 张三"+ },+ "already_prepared": false+ }}```-**进度详情字段(progress_detail):**+**进度阶段**:+1. `reading`: 读取图谱实体 (0-20%)+2. `generating_profiles`: 生成Agent人设 (20-70%)+3. `generating_config`: 生成模拟配置 (70-90%)+4. `copying_scripts`: 准备模拟脚本 (90-100%)-| 字段 | 类型 | 说明 |-|------|------|------|-| `current_stage` | string | 当前阶段标识 (reading/generating_profiles/generating_config/copying_scripts) |-| `current_stage_name` | string | 当前阶段中文名称 |-| `stage_index` | int | 当前阶段序号 (1-4) |-| `total_stages` | int | 总阶段数 (4) |-| `stage_progress` | int | 当前阶段内进度 (0-100) |-| `current_item` | int | 当前处理的项目序号 |-| `total_items` | int | 当前阶段总项目数 |-| `item_description` | string | 当前项目描述 |+----**阶段说明:**+#### 4. 启动模拟-| 阶段 | 名称 | 权重 | 说明 |-|------|------|------|------|-| 1 | 读取图谱实体 | 0-20% | 从Zep读取并过滤实体 |-| 2 | 生成Agent人设 | 20-70% | 为每个实体生成OASIS Profile |-| 3 | 生成模拟配置 | 70-90% | LLM智能生成模拟参数 |-| 4 | 准备模拟脚本 | 90-100% | 复制预设脚本到模拟目录 |--**状态值(status):**-- `pending` - 等待中-- `processing` - 处理中-- `completed` - 已完成(此时result包含结果)-- `failed` - 失败(此时error包含错误信息)--**完成后的响应:**+**接口**: `POST /api/simulation/start`++**请求参数**:```json{- "success": true,- "data": {- "task_id": "task_xxxx",- "status": "completed",- "progress": 100,- "message": "任务完成",- "result": {- "simulation_id": "sim_xxxx",- "project_id": "proj_xxxx",- "graph_id": "mirofish_xxxx",- "status": "ready",- "entities_count": 93,- "profiles_count": 93,- "entity_types": ["University", "Student", ...],- "config_generated": true,- "error": null- }- }+ "simulation_id": "sim_10b494550540",+ "platform": "parallel"}```-| 字段 | 类型 | 必填 | 说明 |-|------|------|------|------|-| `entity_types` | array | 否 | 指定实体类型进行过滤 |-| `use_llm_for_profiles` | boolean | 否 | 是否使用LLM生成人设,默认true |--**注意**:`simulation_requirement`和`document_text`自动从项目中获取+| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| simulation_id | String | 是 | - | 模拟ID |+| platform | String | 否 | parallel | 运行平台: twitter/reddit/parallel |-**响应示例:**+**返回示例**:```json{- "success": true,- "data": {- "simulation_id": "sim_abc123def456",- "status": "ready",- "entities_count": 45,- "profiles_count": 45,- "entity_types": ["Student", "PublicFigure", "University"],- "config_generated": true,- "config_reasoning": "根据武汉大学图书馆事件的特点,设置72小时模拟时长...",- "run_instructions": {- "simulation_dir": "/path/to/sim_xxx",- "commands": {...},- "instructions": "..."- }- }+ "success": true,+ "data": {+ "simulation_id": "sim_10b494550540",+ "runner_status": "running",+ "process_pid": 12345,+ "twitter_running": true,+ "reddit_running": true,+ "started_at": "2025-12-02T11:00:00"+ }}```----### 获取模拟状态+#### 5. 停止模拟-**GET** `/api/simulation/{simulation_id}`+**接口**: `POST /api/simulation/stop`-**响应示例:**+**请求参数**:```json{- "success": true,- "data": {- "simulation_id": "sim_abc123def456",- "status": "ready",- "entities_count": 45,- "profiles_count": 45,- "entity_types": ["Student", "PublicFigure"],- "current_round": 0,- "twitter_status": "not_started",- "reddit_status": "not_started"- }+ "simulation_id": "sim_10b494550540"}```------### 列出所有模拟--**GET** `/api/simulation/list`--| Query参数 | 类型 | 说明 |-|-----------|------|------|-| `project_id` | string | 按项目ID过滤(可选) |-------### 获取Agent Profile--**GET** `/api/simulation/{simulation_id}/profiles`--| Query参数 | 类型 | 说明 |-|-----------|------|------|-| `platform` | string | 平台类型:reddit 或 twitter |--**响应示例:**+**返回示例**:```json{- "success": true,- "data": {- "platform": "reddit",- "count": 45,- "profiles": [- {- "user_id": 0,- "user_name": "yangjingyuan_123",- "name": "杨景媛",- "bio": "武汉大学学生,关注教育公平与学生权益",- "persona": "杨景媛是一名积极参与社会讨论的大学生,性格内敛但观点鲜明...",- "karma": 1500,- "age": 22,- "gender": "female",- "mbti": "INFJ",- "country": "China",- "profession": "Student",- "interested_topics": ["Education", "Social Issues"]- }- ]- }+ "success": true,+ "data": {+ "simulation_id": "sim_10b494550540",+ "runner_status": "stopped",+ "completed_at": "2025-12-02T12:00:00"+ }}```----### 获取模拟配置--**GET** `/api/simulation/{simulation_id}/config`+#### 6. 获取运行状态-获取LLM智能生成的完整配置,包含:-- `time_config`: 时间配置-- `agent_configs`: 每个Agent的活动配置-- `event_config`: 事件配置-- `generation_reasoning`: LLM的配置推理说明-------### 下载文件--| 接口 | 说明 |-|------|------|-| GET `/api/simulation/{id}/config/download` | 下载配置文件 |-| GET `/api/simulation/{id}/script/{script_name}/download` | 下载脚本文件 |--**脚本名称:**-- `run_twitter_simulation.py`-- `run_reddit_simulation.py`-- `run_parallel_simulation.py`-------### 直接生成Profile--**POST** `/api/simulation/generate-profiles`--不创建模拟,直接从图谱生成Agent Profile。+**接口**: `GET /api/simulation/{simulation_id}/run-status`+**返回示例**:```json{- "graph_id": "mirofish_xxxx",- "entity_types": ["Student", "PublicFigure"],- "use_llm": true,- "platform": "reddit"+ "success": true,+ "data": {+ "simulation_id": "sim_10b494550540",+ "runner_status": "running",+ "current_round": 5,+ "total_rounds": 144,+ "progress_percent": 3.5,+ "simulated_hours": 2,+ "total_simulation_hours": 72,+ "twitter_running": true,+ "reddit_running": true,+ "twitter_actions_count": 150,+ "reddit_actions_count": 200,+ "total_actions_count": 350,+ "started_at": "2025-12-02T11:00:00",+ "updated_at": "2025-12-02T11:30:00"+ }}```----## 模拟运行控制接口--### 开始模拟+#### 7. 获取详细状态(含最近动作)-**POST** `/api/simulation/start`+**接口**: `GET /api/simulation/{simulation_id}/run-status/detail`-启动OASIS模拟,在后台运行。--**请求(JSON):**-```json-{- "simulation_id": "sim_xxxx", // 必填- "platform": "parallel" // 可选: twitter / reddit / parallel (默认)-}-```--**响应示例:**+**返回示例**:```json{- "success": true,- "data": {- "simulation_id": "sim_xxxx",- "runner_status": "running",- "process_pid": 12345,- "twitter_running": true,- "reddit_running": true,- "total_rounds": 144,- "total_simulation_hours": 72,- "started_at": "2025-12-01T10:00:00"- }+ "success": true,+ "data": {+ ... (基本状态同上) ...,+ "recent_actions": [+ {+ "round_num": 5,+ "timestamp": "2025-12-02T11:30:15",+ "platform": "twitter",+ "agent_id": 3,+ "agent_name": "张三_123",+ "action_type": "CREATE_POST",+ "action_args": {+ "content": "对学术不端事件的看法..."+ },+ "result": "post_id_123",+ "success": true+ },+ ...+ ]+ }}```----### 停止模拟--**POST** `/api/simulation/stop`+#### 8. 其他接口-停止正在运行的模拟。+**获取实体列表**: `GET /api/simulation/entities/{graph_id}`-**请求(JSON):**-```json-{- "simulation_id": "sim_xxxx" // 必填-}-```--**响应示例:**-```json-{- "success": true,- "data": {- "simulation_id": "sim_xxxx",- "runner_status": "stopped",- "completed_at": "2025-12-01T12:00:00",- "twitter_actions_count": 500,- "reddit_actions_count": 650- }-}-```-----+**获取模拟配置**: `GET /api/simulation/{simulation_id}/config`-## 实时状态监控接口+**获取Agent人设**: `GET /api/simulation/{simulation_id}/profiles?platform=reddit`-### 获取运行状态(基础)+**获取动作历史**: `GET /api/simulation/{simulation_id}/actions?limit=100&platform=twitter`-**GET** `/api/simulation/{simulation_id}/run-status`+**获取时间线**: `GET /api/simulation/{simulation_id}/timeline?start_round=0&end_round=10`-获取模拟运行的实时状态,用于前端轮询。+**获取Agent统计**: `GET /api/simulation/{simulation_id}/agent-stats`-**响应示例:**-```json-{- "success": true,- "data": {- "simulation_id": "sim_xxxx",- "runner_status": "running",- "current_round": 25,- "total_rounds": 144,- "progress_percent": 17.4,- "simulated_hours": 12,- "total_simulation_hours": 72,- "twitter_running": true,- "reddit_running": true,- "twitter_actions_count": 150,- "reddit_actions_count": 200,- "total_actions_count": 350,- "started_at": "2025-12-01T10:00:00",- "updated_at": "2025-12-01T10:30:00"- }-}-```+**获取帖子**: `GET /api/simulation/{simulation_id}/posts?platform=reddit&limit=50`-**运行状态值(runner_status):**-- `idle` - 未运行-- `starting` - 启动中-- `running` - 运行中-- `paused` - 已暂停-- `stopping` - 停止中-- `stopped` - 已停止-- `completed` - 已完成-- `failed` - 失败+**获取评论**: `GET /api/simulation/{simulation_id}/comments?post_id=123`----### 获取运行状态(详细,含最近动作)+## 数据模型-**GET** `/api/simulation/{simulation_id}/run-status/detail`+### 1. Project (项目模型)-获取详细运行状态,包含最近的Agent动作列表,**用于前端实时展示动态**。+**文件**: `app/models/project.py`-**响应示例:**-```json-{- "success": true,- "data": {- "simulation_id": "sim_xxxx",- "runner_status": "running",- "current_round": 25,- "progress_percent": 17.4,- "recent_actions": [- {- "round_num": 25,- "timestamp": "2025-12-01T10:30:00",- "platform": "twitter",- "agent_id": 3,- "agent_name": "Entity Name",- "action_type": "CREATE_POST",- "action_args": {"content": "Post content..."},- "result": null,- "success": true- },- {- "round_num": 25,- "timestamp": "2025-12-01T10:29:55",- "platform": "reddit",- "agent_id": 7,- "agent_name": "Another Entity",- "action_type": "LIKE_POST",- "action_args": {"post_id": 5},- "success": true- }- ]- }-}-```+**字段**:+```python+project_id: str # 项目ID (proj_xxx)+name: str # 项目名称+status: ProjectStatus # 状态+created_at: str # 创建时间+updated_at: str # 更新时间----+# 文件信息+files: List[Dict] # 上传的文件列表+total_text_length: int # 文本总长度-### 获取动作历史+# 本体信息+ontology: Dict # 实体类型和关系类型+analysis_summary: str # 分析摘要-**GET** `/api/simulation/{simulation_id}/actions`+# 图谱信息+graph_id: str # Zep图谱ID+graph_build_task_id: str # 构建任务ID-获取完整的Agent动作历史记录。+# 配置+simulation_requirement: str # 模拟需求+chunk_size: int # 文本块大小+chunk_overlap: int # 块重叠大小-**Query参数:**+# 错误信息+error: str # 错误描述+```-| 参数 | 类型 | 说明 |-|------|------|------|-| `limit` | int | 返回数量(默认100) |-| `offset` | int | 偏移量(默认0) |-| `platform` | string | 过滤平台(twitter/reddit) |-| `agent_id` | int | 过滤Agent ID |-| `round_num` | int | 过滤轮次 |+**状态枚举**:+```python+CREATED = "created" # 已创建+ONTOLOGY_GENERATED = "ontology_generated" # 本体已生成+GRAPH_BUILDING = "graph_building" # 图谱构建中+GRAPH_COMPLETED = "graph_completed" # 图谱已完成+FAILED = "failed" # 失败+```----### 获取时间线--**GET** `/api/simulation/{simulation_id}/timeline`+### 2. Task (任务模型)-获取按轮次汇总的时间线,用于前端展示进度条和时间线视图。+**文件**: `app/models/task.py`-**Query参数:**--| 参数 | 类型 | 说明 |-|------|------|------|-| `start_round` | int | 起始轮次(默认0) |-| `end_round` | int | 结束轮次(默认全部) |--**响应示例:**-```json-{- "success": true,- "data": {- "rounds_count": 25,- "timeline": [- {- "round_num": 1,- "twitter_actions": 10,- "reddit_actions": 15,- "total_actions": 25,- "active_agents_count": 8,- "active_agents": [0, 1, 3, 5, 7, 10, 12, 15],- "action_types": {"CREATE_POST": 5, "LIKE_POST": 10, "LLM_ACTION": 10},- "first_action_time": "2025-12-01T10:00:00",- "last_action_time": "2025-12-01T10:05:00"- }- ]- }-}+**字段**:+```python+task_id: str # 任务ID (UUID)+task_type: str # 任务类型+status: TaskStatus # 状态+created_at: datetime # 创建时间+updated_at: datetime # 更新时间+progress: int # 进度 (0-100)+message: str # 状态消息+result: Dict # 任务结果+error: str # 错误信息+metadata: Dict # 元数据+progress_detail: Dict # 详细进度+```++**状态枚举**:+```python+PENDING = "pending" # 等待中+PROCESSING = "processing" # 处理中+COMPLETED = "completed" # 已完成+FAILED = "failed" # 失败```----### 获取Agent统计--**GET** `/api/simulation/{simulation_id}/agent-stats`+### 3. SimulationState (模拟状态)-获取每个Agent的活跃度统计,用于展示排行榜。+**文件**: `app/services/simulation_manager.py`-**响应示例:**-```json-{- "success": true,- "data": {- "agents_count": 45,- "stats": [- {- "agent_id": 3,- "agent_name": "Active Agent",- "total_actions": 50,- "twitter_actions": 30,- "reddit_actions": 20,- "action_types": {"CREATE_POST": 10, "LIKE_POST": 25, "REPOST": 15},- "first_action_time": "2025-12-01T10:00:00",- "last_action_time": "2025-12-01T12:30:00"- }- ]- }-}+**字段**:+```python+simulation_id: str # 模拟ID (sim_xxx)+project_id: str # 项目ID+graph_id: str # 图谱ID+enable_twitter: bool # 启用Twitter+enable_reddit: bool # 启用Reddit+status: SimulationStatus # 状态+entities_count: int # 实体数量+profiles_count: int # 人设数量+entity_types: List[str] # 实体类型列表+config_generated: bool # 配置已生成+config_reasoning: str # 配置推理说明+current_round: int # 当前轮次+twitter_status: str # Twitter状态+reddit_status: str # Reddit状态+created_at: str # 创建时间+updated_at: str # 更新时间+error: str # 错误信息```----## 数据库查询接口--### 获取帖子--**GET** `/api/simulation/{simulation_id}/posts`--从模拟数据库获取帖子列表。+### 4. EntityNode (实体节点)-**Query参数:**+**文件**: `app/services/zep_entity_reader.py`-| 参数 | 类型 | 说明 |-|------|------|------|-| `platform` | string | 平台类型(twitter/reddit,默认reddit) |-| `limit` | int | 返回数量(默认50) |-| `offset` | int | 偏移量 |+**字段**:+```python+uuid: str # 实体UUID+name: str # 实体名称+labels: List[str] # 标签列表+summary: str # 摘要+attributes: Dict # 属性字典+related_edges: List[Dict] # 相关边信息+related_nodes: List[Dict] # 关联节点信息+```----### 获取评论+### 5. OasisAgentProfile (Agent人设)-**GET** `/api/simulation/{simulation_id}/comments`+**文件**: `app/services/oasis_profile_generator.py`-从Reddit模拟数据库获取评论列表。+**字段**:+```python+user_id: int # 用户ID+user_name: str # 用户名+name: str # 真实姓名+bio: str # 简介 (200字)+persona: str # 详细人设 (2000字)+karma: int # Reddit积分+friend_count: int # Twitter好友数+follower_count: int # 粉丝数+statuses_count: int # 发帖数+age: int # 年龄+gender: str # 性别 (male/female/other)+mbti: str # MBTI类型+country: str # 国家+profession: str # 职业+interested_topics: List[str] # 兴趣话题+source_entity_uuid: str # 来源实体UUID+source_entity_type: str # 来源实体类型+created_at: str # 创建时间+```-**Query参数:**+----| 参数 | 类型 | 说明 |-|------|------|------|-| `post_id` | string | 过滤帖子ID(可选) |-| `limit` | int | 返回数量(默认50) |-| `offset` | int | 偏移量 |+### 6. SimulationParameters (模拟参数)----+**文件**: `app/services/simulation_config_generator.py`-# 服务层实现细节+**字段**:+```python+simulation_id: str # 模拟ID+project_id: str # 项目ID+graph_id: str # 图谱ID+simulation_requirement: str # 模拟需求++# 时间配置+time_config: TimeSimulationConfig+ ├── total_simulation_hours: int # 总时长(小时)+ ├── minutes_per_round: int # 每轮分钟数+ ├── agents_per_hour_min: int # 每小时最少激活Agent数+ ├── agents_per_hour_max: int # 每小时最多激活Agent数+ ├── peak_hours: List[int] # 高峰时段 [19,20,21,22]+ ├── off_peak_hours: List[int] # 低谷时段 [0,1,2,3,4,5]+ ├── morning_hours: List[int] # 早间时段 [6,7,8]+ ├── work_hours: List[int] # 工作时段 [9-18]+ ├── peak_activity_multiplier: float # 高峰活跃度系数 1.5+ ├── off_peak_activity_multiplier: float # 低谷活跃度系数 0.05+ ├── morning_activity_multiplier: float # 早间活跃度系数 0.4+ └── work_activity_multiplier: float # 工作时段活跃度系数 0.7++# Agent配置列表+agent_configs: List[AgentActivityConfig]+ ├── agent_id: int # Agent ID+ ├── entity_uuid: str # 实体UUID+ ├── entity_name: str # 实体名称+ ├── entity_type: str # 实体类型+ ├── activity_level: float # 活跃度 (0.0-1.0)+ ├── posts_per_hour: float # 每小时发帖数+ ├── comments_per_hour: float # 每小时评论数+ ├── active_hours: List[int] # 活跃时间段+ ├── response_delay_min: int # 最小响应延迟(分钟)+ ├── response_delay_max: int # 最大响应延迟(分钟)+ ├── sentiment_bias: float # 情感倾向 (-1.0到1.0)+ ├── stance: str # 立场 (supportive/opposing/neutral/observer)+ └── influence_weight: float # 影响力权重++# 事件配置+event_config: EventConfig+ ├── initial_posts: List[Dict] # 初始帖子+ ├── scheduled_events: List[Dict] # 定时事件+ ├── hot_topics: List[str] # 热点话题+ └── narrative_direction: str # 舆论方向++# 平台配置+twitter_config: PlatformConfig+reddit_config: PlatformConfig+ ├── platform: str # 平台名称+ ├── recency_weight: float # 时间新鲜度权重+ ├── popularity_weight: float # 热度权重+ ├── relevance_weight: float # 相关性权重+ ├── viral_threshold: int # 病毒传播阈值+ └── echo_chamber_strength: float # 回声室效应强度++# LLM配置+llm_model: str # LLM模型名称+llm_base_url: str # LLM API地址+generated_at: str # 生成时间+generation_reasoning: str # LLM推理说明+```-## 1. ZepEntityReader(Zep实体读取服务)+----**文件:** `app/services/zep_entity_reader.py`+## 服务层详解-### 核心功能+### 1. OntologyGenerator (本体生成器)-| 方法 | 说明 |-|------|------|-| `get_all_nodes(graph_id)` | 获取图谱所有节点 |-| `get_all_edges(graph_id)` | 获取图谱所有边 |-| `filter_defined_entities(graph_id, ...)` | 筛选符合条件的实体 |-| `get_entity_with_context(graph_id, uuid)` | 获取实体完整上下文 |-| `get_entities_by_type(graph_id, type)` | 按类型获取实体 |+**文件**: `app/services/ontology_generator.py`-### 数据结构+**功能**: 使用LLM分析文档内容,生成适合舆论模拟的实体类型和关系类型+**核心方法**:```python-@dataclass-class EntityNode:- uuid: str # 节点UUID- name: str # 实体名称- labels: List[str] # 标签列表 ["Entity", "Student"]- summary: str # 实体摘要- attributes: Dict[str, Any] # 属性字典- related_edges: List[Dict] # 相关边信息- related_nodes: List[Dict] # 关联节点信息+def generate(+ document_texts: List[str],+ simulation_requirement: str,+ additional_context: Optional[str] = None+) -> Dict[str, Any]:+ """+ 生成本体定义- def get_entity_type(self) -> Optional[str]:- """获取实体类型(排除默认Entity标签)"""--@dataclass-class FilteredEntities:- entities: List[EntityNode] # 实体列表- entity_types: Set[str] # 发现的实体类型- total_count: int # 总节点数- filtered_count: int # 过滤后数量+ Returns:+ {+ "entity_types": [...], # 10个实体类型(最后2个为Person和Organization)+ "edge_types": [...], # 6-10个关系类型+ "analysis_summary": "..." # 分析摘要+ }+ """```-### 过滤逻辑示例--```python-# Zep返回的节点Labels示例:-# 符合预定义类型: ["Entity", "Student"]-# 不符合预定义类型: ["Entity"]+**设计原则**:+- 必须返回**10个实体类型**,最后2个为兜底类型+- 实体必须是现实中可以发声的主体(人/组织)+- 属性名不能使用Zep保留字+- 关系类型要反映社交媒体互动-for node in all_nodes:- labels = node.get("labels", [])- custom_labels = [l for l in labels if l not in ["Entity", "Node"]]-- if not custom_labels:- # 只有默认标签,跳过- continue-- # 保留符合条件的实体- entity_type = custom_labels[0]- filtered_entities.append(node)-```+**LLM提示词要点**:+- 系统角色: 知识图谱本体设计专家+- 任务背景: 社交媒体舆论模拟+- 输出格式: 严格的JSON结构+- 实体类型层次: 具体类型(8个) + 兜底类型(2个)----## 2. OasisProfileGenerator(Agent Profile生成器)--**文件:** `app/services/oasis_profile_generator.py`+### 2. GraphBuilderService (图谱构建服务)-### 核心功能+**文件**: `app/services/graph_builder.py`-| 方法 | 说明 |-|------|------|-| `generate_profile_from_entity(entity, user_id)` | 从实体生成单个Profile(带详细人设) |-| `generate_profiles_from_entities(entities, graph_id)` | 批量生成Profile |-| `save_profiles(profiles, path, platform)` | 保存Profile文件 |-| `_search_zep_for_entity(entity_name)` | 调用Zep检索获取额外上下文 |+**功能**: 调用Zep API构建知识图谱-### 优化特性(v2.0)+**核心方法**:+```python+def create_graph(name: str) -> str:+ """创建Zep图谱"""-1. **Zep混合搜索功能**:使用多种查询策略获取丰富的实体信息-2. **区分实体类型**:个人实体 vs 群体/机构实体,使用不同的提示词-3. **详细人设生成**:生成500字以上的详细人设描述+def set_ontology(graph_id: str, ontology: Dict):+ """设置图谱本体(动态创建Pydantic类)"""-### Zep混合搜索策略+def add_text_batches(+ graph_id: str,+ chunks: List[str],+ batch_size: int = 3,+ progress_callback: Optional[Callable] = None+) -> List[str]:+ """分批添加文本,返回episode UUIDs"""-`_search_zep_for_entity()` 方法采用多种搜索策略获取丰富信息:+def _wait_for_episodes(+ episode_uuids: List[str],+ progress_callback: Optional[Callable] = None,+ timeout: int = 600+):+ """等待所有episode处理完成"""-**查询策略:**-```python-queries = [- f"总结{entity_name}的全部活动、事件和行为",- f"{entity_name}与其他实体的关系和互动",- f"{entity_name}的背景、历史和重要信息",- f"关于{entity_name}的所有事实和描述",-]+def get_graph_data(graph_id: str) -> Dict:+ """获取完整图谱数据(节点和边)"""```-**说明:** Zep没有内置的混合搜索接口,需要分别搜索edges和nodes。我们使用**并行请求**同时执行两个搜索:+**关键技术点**:+1. **动态类创建**: 根据本体定义动态创建Pydantic类+2. **批量上传**: 避免一次性提交大量数据+3. **异步等待**: 轮询episode的`processed`状态+4. **容错重试**: 所有API调用带重试机制++---++### 3. ZepEntityReader (实体读取器)++**文件**: `app/services/zep_entity_reader.py`+**功能**: 从Zep图谱读取并过滤实体++**核心方法**:```python-# 并行执行edges和nodes搜索-with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:- edge_future = executor.submit(search_edges) # scope="edges"- node_future = executor.submit(search_nodes) # scope="nodes"+def get_all_nodes(graph_id: str) -> List[Dict]:+ """获取所有节点(带重试)"""++def get_all_edges(graph_id: str) -> List[Dict]:+ """获取所有边(带重试)"""++def filter_defined_entities(+ graph_id: str,+ defined_entity_types: Optional[List[str]] = None,+ enrich_with_edges: bool = True+) -> FilteredEntities:+ """+ 筛选符合预定义类型的实体- edge_result = edge_future.result(timeout=30)- node_result = node_future.result(timeout=30)+ 筛选逻辑:+ - 只保留Labels中包含除"Entity"和"Node"外的自定义标签的节点+ - 如果指定了entity_types,只保留匹配的类型+ - 可选:获取每个实体的相关边和关联节点+ """++def get_entity_with_context(+ graph_id: str,+ entity_uuid: str+) -> Optional[EntityNode]:+ """获取单个实体及其完整上下文"""```-**搜索参数:**+**容错机制**:+- 所有Zep API调用带**3次重试**+- 使用指数退避策略+- 详细的日志记录++---++### 4. OasisProfileGenerator (人设生成器)-| 搜索类型 | scope | limit | 说明 |-|----------|-------|-------|------|-| 边搜索 | edges | 30 | 获取事实/关系信息 |-| 节点搜索 | nodes | 20 | 获取相关实体摘要 |+**文件**: `app/services/oasis_profile_generator.py`-**关键参数:**-- 必须传递 `graph_id` 参数,否则Zep API会返回400错误-- 使用 `rrf` (Reciprocal Rank Fusion) reranker,稳定可靠-- 使用线程池并行执行,提高效率+**功能**: 将图谱实体转换为OASIS Agent Profile-**返回数据结构:**+**核心方法**:```python-{- "facts": [...], # 事实列表(来自edges)- "node_summaries": [...], # 相关节点摘要(来自nodes)- "context": "..." # 综合上下文文本-}+def generate_profile_from_entity(+ entity: EntityNode,+ user_id: int,+ use_llm: bool = True+) -> OasisAgentProfile:+ """+ 从实体生成Agent人设++ 步骤:+ 1. 构建实体上下文(属性+边+关联节点+Zep检索)+ 2. 使用LLM生成详细人设(2000字persona)+ 3. 返回OasisAgentProfile对象+ """++def generate_profiles_from_entities(+ entities: List[EntityNode],+ use_llm: bool = True,+ progress_callback: Optional[callable] = None,+ graph_id: Optional[str] = None,+ parallel_count: int = 5+) -> List[OasisAgentProfile]:+ """+ 批量生成人设(支持并行)++ 特性:+ - 并行生成(默认5个并发)+ - Zep混合检索增强上下文+ - 区分个人实体和机构实体+ - 容错处理(失败则使用规则生成)+ """```-### LLM生成与JSON修复+**LLM提示词设计**:+- **个人实体**: 生成2000字详细人设(基本信息+背景+性格+社交行为+立场观点+个人记忆)+- **机构实体**: 生成官方账号设定(机构信息+账号定位+发言风格+发布内容+立场态度+机构记忆)+- **输出格式**: JSON (bio, persona, age, gender, mbti, country, profession, interested_topics)-为了避免LLM生成的JSON解析失败,实现了以下优化:+**容错措施**:+1. LLM调用失败:最多重试3次+2. JSON解析失败:尝试修复JSON+3. 完全失败:使用规则生成基础人设-1. **不限制max_tokens**:让LLM自由发挥,充分利用模型的上下文能力-2. **多次重试机制**:最多3次尝试,每次降低temperature-3. **截断检测与修复**:检测`finish_reason='length'`,自动闭合JSON-4. **完善JSON修复机制**:- - `_fix_truncated_json()`: 修复被截断的JSON(闭合括号和字符串)- - `_try_fix_json()`: 多级修复策略- - 提取JSON部分- - 替换字符串中的换行符- - 移除控制字符- - 从损坏JSON中提取部分信息-5. **字段验证**:确保必需字段存在,缺失时使用entity_summary填充+----**错误处理流程**:-```-LLM调用 → 检查截断 → JSON解析 → 修复尝试 → 部分提取 → 规则生成-```+### 5. SimulationConfigGenerator (配置生成器)-### 并行生成与实时输出+**文件**: `app/services/simulation_config_generator.py`-支持并行生成Agent人设,提高生成效率:+**功能**: 使用LLM智能生成模拟配置参数+**核心方法**:```python-profiles = generator.generate_profiles_from_entities(- entities=filtered.entities,- use_llm=True,- graph_id="mirofish_xxx",- parallel_count=5 # 并行生成数量,默认5-)-```+def generate_config(+ simulation_id: str,+ project_id: str,+ graph_id: str,+ simulation_requirement: str,+ document_text: str,+ entities: List[EntityNode],+ enable_twitter: bool = True,+ enable_reddit: bool = True,+ progress_callback: Optional[Callable] = None,+) -> SimulationParameters:+ """+ 智能生成完整模拟配置++ 分步生成策略(避免一次性生成过长):+ 1. 生成时间配置(符合中国人作息)+ 2. 生成事件配置(热点话题+初始帖子)+ 3. 分批生成Agent配置(每批15个)+ 4. 生成平台配置+ """+```++**时间配置特点**:+- **高峰时段**: 19-22点(活跃度系数1.5)+- **低谷时段**: 0-5点(活跃度系数0.05)+- **早间时段**: 6-8点(活跃度系数0.4)+- **工作时段**: 9-18点(活跃度系数0.7)++**Agent配置规则**:+- **官方机构**: 活跃度低(0.1-0.3),工作时间活动,响应慢,影响力高(2.5-3.0)+- **媒体**: 活跃度中(0.4-0.6),全天活动,响应快,影响力高(2.0-2.5)+- **个人/学生**: 活跃度高(0.6-0.9),晚间活动,响应快,影响力低(0.8-1.2)+- **专家/教授**: 活跃度中(0.4-0.6),工作+晚间,影响力中高(1.5-2.0)-**API参数**:-```json-POST /api/simulation/prepare-{- "simulation_id": "sim_xxx",- "parallel_profile_count": 5, // 可选,并行生成人设数量,默认5- "force_regenerate": false // 可选,强制重新生成,默认false-}-```+---++### 6. SimulationManager (模拟管理器)-**实时输出**:-- 每生成一个人设,立即输出到控制台(完整内容不截断)-- 包含用户名、简介、详细人设、年龄、性别、MBTI等信息-- 方便实时监控生成进度和质量+**文件**: `app/services/simulation_manager.py`-### 避免重复生成+**功能**: 管理模拟的完整生命周期-系统会自动检测已完成的准备工作,避免重复生成:+**核心方法**:+```python+def create_simulation(+ project_id: str,+ graph_id: str,+ enable_twitter: bool = True,+ enable_reddit: bool = True,+) -> SimulationState:+ """创建新模拟"""++def prepare_simulation(+ simulation_id: str,+ simulation_requirement: str,+ document_text: str,+ defined_entity_types: Optional[List[str]] = None,+ use_llm_for_profiles: bool = True,+ progress_callback: Optional[callable] = None,+ parallel_profile_count: int = 3+) -> SimulationState:+ """+ 准备模拟环境(全程自动化)++ 步骤:+ 1. 读取并过滤图谱实体+ 2. 并行生成Agent人设(带Zep检索增强)+ 3. LLM智能生成模拟配置+ 4. 保存配置和人设文件+ """-**检测条件**:-1. `state.json` 存在且 `config_generated=true`-2. 必要文件存在:`reddit_profiles.json`, `twitter_profiles.csv`, `simulation_config.json`+def get_simulation(simulation_id: str) -> Optional[SimulationState]:+ """获取模拟状态"""-**API响应**:-```json-// 已准备完成时-{- "success": true,- "data": {- "simulation_id": "sim_xxx",- "status": "ready",- "message": "已有完成的准备工作,无需重复生成",- "already_prepared": true,- "prepare_info": {- "entities_count": 93,- "profiles_count": 93,- "entity_types": ["Student", "Professor", ...],- "existing_files": [...]- }- }-}+def list_simulations(project_id: Optional[str] = None) -> List[SimulationState]:+ """列出所有模拟"""```-**强制重新生成**:-```json-POST /api/simulation/prepare-{- "simulation_id": "sim_xxx",- "force_regenerate": true // 忽略已有准备,强制重新生成-}+**数据存储**:+```+uploads/simulations/sim_xxx/+├── state.json # 模拟状态+├── simulation_config.json # 模拟配置(LLM生成)+├── reddit_profiles.json # Reddit人设(JSON格式)+├── twitter_profiles.csv # Twitter人设(CSV格式)+├── run_state.json # 运行状态+├── simulation.log # 主日志+├── twitter/+│ ├── actions.jsonl # Twitter动作日志+│ └── twitter_simulation.db # Twitter数据库+└── reddit/+ ├── actions.jsonl # Reddit动作日志+ └── reddit_simulation.db # Reddit数据库```-### 实体类型分类+----```python-# 个人类型实体 - 生成具体人物设定-INDIVIDUAL_ENTITY_TYPES = [- "student", "alumni", "professor", "person", "publicfigure",- "expert", "faculty", "official", "journalist", "activist"-]--# 群体/机构类型实体 - 生成官方账号设定-GROUP_ENTITY_TYPES = [- "university", "governmentagency", "organization", "ngo",- "mediaoutlet", "company", "institution", "group", "community"-]-```+### 7. SimulationRunner (模拟运行器)++**文件**: `app/services/simulation_runner.py`-### Profile数据结构+**功能**: 在后台运行OASIS模拟并实时监控+**核心方法**:```python-@dataclass-class OasisAgentProfile:- # 基础字段- user_id: int # 用户ID- user_name: str # 用户名- name: str # 显示名称- bio: str # 简介(max 150字符)- persona: str # 详细人设描述(500字以上)-- # Reddit字段- karma: int = 1000+@classmethod+def start_simulation(+ cls,+ simulation_id: str,+ platform: str = "parallel"+) -> SimulationRunState:+ """+ 启动模拟- # Twitter字段- friend_count: int = 100- follower_count: int = 150- statuses_count: int = 500+ 步骤:+ 1. 启动模拟进程(subprocess)+ 2. 创建监控线程+ 3. 解析动作日志+ 4. 实时更新状态+ """++@classmethod+def stop_simulation(cls, simulation_id: str) -> SimulationRunState:+ """+ 停止模拟- # 人设详情- age: Optional[int] = None- gender: Optional[str] = None- mbti: Optional[str] = None # INTJ, ENFP等- country: Optional[str] = None- profession: Optional[str] = None- interested_topics: List[str] = []-- # 来源信息- source_entity_uuid: Optional[str] = None- source_entity_type: Optional[str] = None-```--### 详细人设生成示例--**个人实体人设结构:**-```markdown-## 一、基本信息-- 姓名/称呼、年龄、职业/身份-- 教育背景、所在地--## 二、人物背景-- 过去的重要经历-- 与事件的关联-- 社会关系网络+ 使用进程组终止(确保子进程也被终止)+ """++@classmethod+def get_run_state(cls, simulation_id: str) -> Optional[SimulationRunState]:+ """获取运行状态"""++@classmethod+def get_actions(+ cls,+ simulation_id: str,+ limit: int = 100,+ offset: int = 0,+ platform: Optional[str] = None,+ agent_id: Optional[int] = None,+ round_num: Optional[int] = None+) -> List[AgentAction]:+ """获取动作历史(支持过滤)"""++@classmethod+def cleanup_all_simulations(cls):+ """清理所有运行中的模拟进程(服务器关闭时调用)"""+```++**进程管理**:+- 使用`subprocess.Popen`启动模拟脚本+- 使用`start_new_session=True`创建新进程组+- 使用`os.killpg`终止整个进程组+- 支持优雅关闭(SIGTERM)和强制终止(SIGKILL)++**日志解析**:+- 实时读取`twitter/actions.jsonl`和`reddit/actions.jsonl`+- 解析每个Agent的动作记录+- 更新运行状态和进度+- 保存最近50个动作用于前端展示-## 三、性格特征-- MBTI类型及表现-- 核心性格特点-- 情绪表达方式--## 四、社交媒体行为模式-- 发帖频率和时间-- 内容偏好类型-- 语言风格特点+----## 五、立场与观点-- 对核心话题的态度-- 可能被激怒/感动的内容+## 工具类-## 六、独特特征-- 口头禅、个人爱好等-```+### 1. FileParser (文件解析器)-### Profile生成策略+**文件**: `app/utils/file_parser.py`-**1. LLM生成(默认)**+**功能**: 从PDF/MD/TXT文件提取文本-使用LLM根据实体信息生成详细人设:+**支持格式**:+- PDF: 使用PyMuPDF+- Markdown: 直接读取+- TXT: 直接读取+**核心方法**:```python-prompt = f"""-Entity: {entity_name} ({entity_type})-Summary: {entity_summary}-Context: {related_edges_and_nodes}--Generate a social media user profile with:-- bio (max 150 chars)-- persona (detailed description)-- age, gender, mbti, country-- profession, interested_topics-"""+@classmethod+def extract_text(cls, file_path: str) -> str:+ """从文件提取文本"""++@classmethod+def extract_from_multiple(cls, file_paths: List[str]) -> str:+ """从多个文件提取并合并文本"""++def split_text_into_chunks(+ text: str,+ chunk_size: int = 500,+ overlap: int = 50+) -> List[str]:+ """+ 文本分块++ 特点:+ - 尝试在句子边界分割+ - 支持中英文句子结束符+ - 块之间有重叠(overlap)+ """```-**2. 规则生成(Fallback)**--根据实体类型使用预定义模板:--| 实体类型 | 生成策略 |-|----------|----------|-| Student/Alumni | 年龄18-30,学生身份,关注教育话题 |-| PublicFigure/Expert | 年龄35-60,专业人士,政治经济话题 |-| MediaOutlet | 媒体官方账号,新闻时事话题 |-| University/GovernmentAgency | 机构官方账号,政策公告话题 |-----## 3. SimulationConfigGenerator(模拟配置智能生成器)--**文件:** `app/services/simulation_config_generator.py`+### 2. LLMClient (LLM客户端)-### 核心功能+**文件**: `app/utils/llm_client.py`-使用LLM分析模拟需求、文档内容、图谱实体信息,自动生成最佳的模拟参数配置。+**功能**: 统一的LLM调用封装(OpenAI格式)-**采用分步生成策略**(避免一次性生成过长内容导致失败):-1. 生成时间配置(轻量级)-2. 生成事件配置和热点话题-3. 分批生成Agent配置(**每批5个**,保证生成质量)-4. 生成平台配置+**核心方法**:+```python+def chat(+ self,+ messages: List[Dict[str, str]],+ temperature: float = 0.7,+ max_tokens: int = 4096,+ response_format: Optional[Dict] = None+) -> str:+ """发送聊天请求"""++def chat_json(+ self,+ messages: List[Dict[str, str]],+ temperature: float = 0.3,+ max_tokens: int = 4096+) -> Dict[str, Any]:+ """发送聊天请求并返回JSON"""+```++**配置**:+- 从`Config.LLM_API_KEY`读取API密钥+- 从`Config.LLM_BASE_URL`读取API地址+- 从`Config.LLM_MODEL_NAME`读取模型名称-| 方法 | 说明 |-|------|------|-| `generate_config(...)` | 智能生成完整模拟配置(分步) |-| `_generate_time_config(...)` | 生成时间配置 |-| `_generate_event_config(...)` | 生成事件配置 |-| `_generate_agent_configs_batch(...)` | 分批生成Agent配置 |-| `_generate_agent_config_by_rule(...)` | 规则生成(LLM失败时) |+----### 中国人作息时间配置+### 3. Logger (日志管理)-系统针对中国用户群体,采用符合北京时间的作息习惯:+**文件**: `app/utils/logger.py`-| 时段 | 时间范围 | 活跃度系数 | 说明 |-|------|----------|------------|------|-| 深夜 | 0:00-5:59 | 0.05 | 几乎无人活动 |-| 早间 | 6:00-8:59 | 0.4 | 逐渐醒来 |-| 工作 | 9:00-18:59 | 0.7 | 工作时段中等活跃 |-| 高峰 | 19:00-22:59 | 1.5 | 晚间最活跃 |-| 夜间 | 23:00-23:59 | 0.5 | 活跃度下降 |+**功能**: 统一的日志配置-### LLM智能生成的配置内容+**特点**:+- 双输出:控制台(INFO+) + 文件(DEBUG+)+- 按日期命名日志文件+- 日志轮转(10MB,保留5个备份)+- 详细格式(文件) + 简洁格式(控制台)-**1. TimeSimulationConfig(时间配置)**+**使用方法**:```python-@dataclass-class TimeSimulationConfig:- total_simulation_hours: int = 72 # 模拟总时长(小时)- minutes_per_round: int = 30 # 每轮代表的时间(分钟)- agents_per_hour_min: int = 5 # 每小时激活Agent数量(最小)- agents_per_hour_max: int = 20 # 每小时激活Agent数量(最大)- peak_hours: List[int] = [19,20,21,22] # 高峰时段(晚间)- off_peak_hours: List[int] = [0,1,2,3,4,5] # 低谷时段(凌晨)- peak_activity_multiplier: float = 1.5 # 高峰活跃度乘数- off_peak_activity_multiplier: float = 0.05 # 凌晨活跃度极低- morning_hours: List[int] = [6,7,8] # 早间时段- morning_activity_multiplier: float = 0.4- work_hours: List[int] = [9-18] # 工作时段- work_activity_multiplier: float = 0.7-```+from app.utils.logger import get_logger-**2. AgentActivityConfig(每个Agent的活动配置)**-```python-@dataclass-class AgentActivityConfig:- agent_id: int- entity_uuid: str- entity_name: str- entity_type: str-- activity_level: float = 0.5 # 整体活跃度 (0.0-1.0)- posts_per_hour: float = 1.0 # 每小时发帖频率- comments_per_hour: float = 2.0 # 每小时评论频率- active_hours: List[int] # 活跃时间段 (0-23)- response_delay_min: int = 5 # 响应延迟最小值(分钟)- response_delay_max: int = 60 # 响应延迟最大值(分钟)- sentiment_bias: float = 0.0 # 情感倾向 (-1到1)- stance: str = "neutral" # 立场 (supportive/opposing/neutral/observer)- influence_weight: float = 1.0 # 影响力权重+logger = get_logger('mirofish.mymodule')+logger.debug("调试信息")+logger.info("普通信息")+logger.warning("警告")+logger.error("错误")```-**3. 不同实体类型的默认参数差异(符合中国人作息)**--| 实体类型 | 活跃度 | 发帖频率 | 活跃时段 | 响应延迟 | 影响力 |-|----------|--------|----------|----------|----------|--------|-| University/GovernmentAgency | 0.2 | 0.1/小时 | 9:00-17:59(工作时间) | 60-240分钟 | 3.0 |-| MediaOutlet | 0.5 | 0.8/小时 | 7:00-23:59(全天) | 5-30分钟 | 2.5 |-| Professor/Expert | 0.4 | 0.3/小时 | 8:00-21:59(工作+晚间) | 15-90分钟 | 2.0 |-| Student | 0.8 | 0.6/小时 | 8-13, 18-23(上午+晚间) | 1-15分钟 | 0.8 |-| Alumni | 0.6 | 0.4/小时 | 12-13, 19-23(午休+晚间) | 5-30分钟 | 1.0 |-| Person(普通人) | 0.7 | 0.5/小时 | 9-13, 18-23(白天+晚间) | 2-20分钟 | 1.0 |--**注意**:凌晨0-5点所有实体类型都几乎不活动(符合中国人作息习惯)-----## 4. SimulationManager(模拟管理器)+### 4. Retry (重试机制)-**文件:** `app/services/simulation_manager.py`+**文件**: `app/utils/retry.py`-### 核心功能+**功能**: API调用重试装饰器-| 方法 | 说明 |-|------|------|-| `create_simulation(project_id, graph_id, ...)` | 创建模拟 |-| `prepare_simulation(simulation_id, ...)` | 准备模拟环境(调用配置生成器) |-| `get_simulation(simulation_id)` | 获取模拟状态 |-| `get_profiles(simulation_id, platform)` | 获取Profile |-| `get_simulation_config(simulation_id)` | 获取模拟配置 |-| `get_run_instructions(simulation_id)` | 获取运行说明 |+**核心方法**:+```python+@retry_with_backoff(+ max_retries=3,+ initial_delay=1.0,+ backoff_factor=2.0,+ exceptions=(ConnectionError, TimeoutError)+)+def call_api():+ ...+```-### 模拟状态流转+**特点**:+- 指数退避+- 随机抖动(避免雷击)+- 自定义异常类型+- 重试回调-```-created → preparing → ready → running → completed- ↓ ↓- failed paused-```+----### 生成的文件结构+## 配置说明-```-uploads/simulations/sim_xxxx/-├── state.json # 模拟状态-├── simulation_config.json # LLM生成的模拟配置(核心文件)-├── reddit_profiles.json # Reddit Agent Profile(JSON格式)-├── twitter_profiles.csv # Twitter Agent Profile(CSV格式)-├── run_reddit_simulation.py # 预设Reddit模拟脚本-├── run_twitter_simulation.py # 预设Twitter模拟脚本-├── run_parallel_simulation.py # 预设双平台并行脚本-├── reddit_simulation.db # Reddit数据库(运行后生成)-└── twitter_simulation.db # Twitter数据库(运行后生成)-```+### 环境变量配置-**重要:OASIS平台的Profile格式要求不同:**+在项目根目录创建`.env`文件:-**Twitter CSV格式**(符合OASIS官方要求):-```csv-user_id,name,username,user_char,description-0,张教授,professor_zhang,"完整人设描述(LLM内部使用)","简短简介(外部显示)"-```-- `user_id`: 从0开始的顺序ID-- `name`: 真实姓名-- `username`: 系统用户名-- `user_char`: 完整人设(bio + persona),注入LLM系统提示,指导Agent行为-- `description`: 简短简介,显示在用户资料页面+```bash+# Flask配置+FLASK_DEBUG=True+FLASK_HOST=0.0.0.0+FLASK_PORT=5001+SECRET_KEY=your-secret-key++# LLM配置(OpenAI兼容接口)+LLM_API_KEY=sk-xxx+LLM_BASE_URL=https://api.openai.com/v1+LLM_MODEL_NAME=gpt-4o-mini-**Reddit JSON格式**:-```json-[- {- "realname": "张教授",- "username": "professor_zhang",- "bio": "简短简介",- "persona": "详细人设描述",- "age": 42,- "gender": "男",- "mbti": "INTJ",- "country": "中国",- "profession": "教授",- "interested_topics": ["高等教育", "学术诚信"]- }-]-```+# Zep配置+ZEP_API_KEY=z_xxx-**user_char vs description 区别**:-| 字段 | 用途 | 可见性 |-|------|------|--------|-| user_char | LLM系统提示,决定Agent如何思考和行动 | 内部使用 |-| description | 用户资料页面的简介 | 其他用户可见 |+# OASIS模拟配置+OASIS_DEFAULT_MAX_ROUNDS=10+```-### 配置文件示例 (simulation_config.json)+### 配置项说明-```json-{- "simulation_id": "sim_abc123",- "project_id": "proj_xxx",- "graph_id": "mirofish_xxx",- "simulation_requirement": "分析武汉大学图书馆事件舆论传播",-- "time_config": {- "total_simulation_hours": 72,- "minutes_per_round": 30,- "agents_per_hour_min": 5,- "agents_per_hour_max": 15,- "peak_hours": [9, 10, 11, 14, 15, 20, 21, 22],- "off_peak_hours": [0, 1, 2, 3, 4, 5],- "peak_activity_multiplier": 1.5,- "off_peak_activity_multiplier": 0.3- },-- "agent_configs": [- {- "agent_id": 0,- "entity_name": "武汉大学",- "entity_type": "University",- "activity_level": 0.15,- "posts_per_hour": 0.08,- "comments_per_hour": 0.02,- "active_hours": [9, 10, 11, 14, 15, 16, 17],- "response_delay_min": 120,- "response_delay_max": 360,- "sentiment_bias": 0.1,- "stance": "neutral",- "influence_weight": 4.0- },- {- "agent_id": 1,- "entity_name": "杨景媛",- "entity_type": "Student",- "activity_level": 0.8,- "posts_per_hour": 0.5,- "comments_per_hour": 2.0,- "active_hours": [7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],- "response_delay_min": 1,- "response_delay_max": 15,- "sentiment_bias": -0.3,- "stance": "opposing",- "influence_weight": 1.5- }- ],-- "event_config": {- "initial_posts": [- {- "poster_agent_id": 1,- "content": "今天在图书馆发生的事情让我非常失望..."- }- ],- "hot_topics": ["图书馆事件", "学生权益", "校方回应"],- "narrative_direction": "事件发酵后各方反应的模拟"- },-- "generation_reasoning": "根据武汉大学图书馆事件的特点:1)涉及学生与校方的冲突,设置学生高活跃度、校方低频但高影响力;2)事件性质属于短期热点,设置72小时模拟时长;3)主要当事人杨景媛设置为高活跃度且持opposing立场..."-}+| 配置项 | 类型 | 默认值 | 说明 |+|--------|------|--------|------|+| FLASK_DEBUG | Boolean | True | 调试模式 |+| FLASK_HOST | String | 0.0.0.0 | 监听地址 |+| FLASK_PORT | Integer | 5001 | 监听端口 |+| SECRET_KEY | String | - | Flask密钥 |+| LLM_API_KEY | String | - | LLM API密钥(必填) |+| LLM_BASE_URL | String | https://api.openai.com/v1 | LLM API地址 |+| LLM_MODEL_NAME | String | gpt-4o-mini | LLM模型名称 |+| ZEP_API_KEY | String | - | Zep API密钥(必填) |+| OASIS_DEFAULT_MAX_ROUNDS | Integer | 10 | 默认模拟轮数 |----## 5. 预设模拟脚本+## 运行指南-**目录:** `backend/scripts/`+### 1. 环境准备-脚本是**预设的**,不是动态生成。每次准备模拟时,脚本会被复制到模拟目录。+```bash+# 1. 激活conda环境+conda activate MiroFish-### 脚本说明+# 2. 安装依赖+cd backend+pip install -r requirements.txt-| 脚本 | 说明 |-|------|------|-| `run_twitter_simulation.py` | Twitter单平台模拟 |-| `run_reddit_simulation.py` | Reddit单平台模拟 |-| `run_parallel_simulation.py` | 双平台并行模拟(推荐) |+# 3. 配置环境变量+cp .env.example .env+# 编辑.env文件,填入API密钥+```-### 脚本工作原理+### 2. 启动服务-```python-# 脚本读取配置文件,自动设置所有参数-class TwitterSimulationRunner:- def __init__(self, config_path: str):- self.config = self._load_config() # 读取simulation_config.json-- def _get_active_agents_for_round(self, env, current_hour, round_num):- """根据时间和配置决定本轮激活哪些Agent"""- time_config = self.config.get("time_config", {})- agent_configs = self.config.get("agent_configs", [])-- # 1. 检查是否高峰/低谷时段,调整激活数量- # 2. 遍历每个Agent配置,检查是否在活跃时间- # 3. 根据activity_level计算激活概率- # 4. 返回本轮应激活的Agent列表- ...-- async def run(self):- # 1. 创建LLM模型- # 2. 加载Agent图- # 3. 执行初始事件(从event_config读取)- # 4. 主循环:根据配置激活不同Agent- ...+```bash+# 启动Flask服务+python run.py```-### 使用方式+服务启动后访问:+- 主页: http://localhost:5001+- 健康检查: http://localhost:5001/health+- API文档: (见上文API接口文档)++### 3. 使用流程++**完整流程示例**:```bash-# 进入模拟目录-cd backend/uploads/simulations/sim_xxxx/+# Step 1: 上传文档并生成本体+curl -X POST http://localhost:5001/api/graph/ontology/generate \+ -F "[email protected]" \+ -F "simulation_requirement=模拟学术不端事件的舆论发展" \+ -F "project_name=学术不端事件"++# 返回: project_id, ontology++# Step 2: 构建图谱+curl -X POST http://localhost:5001/api/graph/build \+ -H "Content-Type: application/json" \+ -d '{+ "project_id": "proj_xxx",+ "graph_name": "学术不端事件图谱"+ }'++# 返回: task_id++# Step 3: 查询构建进度+curl http://localhost:5001/api/graph/task/{task_id}++# 等待status=completed, 获取graph_id++# Step 4: 创建模拟+curl -X POST http://localhost:5001/api/simulation/create \+ -H "Content-Type: application/json" \+ -d '{+ "project_id": "proj_xxx",+ "graph_id": "mirofish_xxx"+ }'++# 返回: simulation_id++# Step 5: 准备模拟+curl -X POST http://localhost:5001/api/simulation/prepare \+ -H "Content-Type: application/json" \+ -d '{+ "simulation_id": "sim_xxx",+ "use_llm_for_profiles": true,+ "parallel_profile_count": 5+ }'++# 返回: task_id++# Step 6: 查询准备进度+curl -X POST http://localhost:5001/api/simulation/prepare/status \+ -H "Content-Type: application/json" \+ -d '{+ "task_id": "task_xxx",+ "simulation_id": "sim_xxx"+ }'++# 等待status=completed++# Step 7: 启动模拟+curl -X POST http://localhost:5001/api/simulation/start \+ -H "Content-Type: application/json" \+ -d '{+ "simulation_id": "sim_xxx",+ "platform": "parallel"+ }'-# 运行模拟-python run_parallel_simulation.py --config simulation_config.json+# Step 8: 实时查询运行状态+curl http://localhost:5001/api/simulation/{sim_xxx}/run-status-# 其他选项-python run_parallel_simulation.py --config simulation_config.json --twitter-only-python run_parallel_simulation.py --config simulation_config.json --reddit-only+# Step 9: 停止模拟+curl -X POST http://localhost:5001/api/simulation/stop \+ -H "Content-Type: application/json" \+ -d '{+ "simulation_id": "sim_xxx"+ }'```----## 6. Profile文件格式说明+## 开发指南-**OASIS对两个平台的Profile格式有不同要求:**+### 添加新的实体类型-### Twitter Profile (CSV格式)+1. 修改本体生成提示词(`app/services/ontology_generator.py`)+2. 更新实体类型参考列表+3. 测试本体生成-```csv-user_id,user_name,name,bio,friend_count,follower_count,statuses_count,created_at-0,user0,User Zero,I am user zero with interests in technology.,100,150,500,2023-01-01-1,user1,User One,Tech enthusiast and coffee lover.,200,250,1000,2023-01-02-```+### 添加新的平台支持-| 字段 | 类型 | 说明 |-|------|------|------|-| `user_id` | int | 用户ID |-| `user_name` | string | 用户名 |-| `name` | string | 显示名称 |-| `bio` | string | 简介 |-| `friend_count` | int | 关注数 |-| `follower_count` | int | 粉丝数 |-| `statuses_count` | int | 发帖数 |-| `created_at` | string | 创建日期 |+1. 在`app/services/oasis_profile_generator.py`添加平台格式转换方法+2. 在`app/services/simulation_manager.py`更新文件保存逻辑+3. 在`scripts/`目录添加平台模拟脚本+4. 更新`SimulationRunner`的平台检测逻辑-### Reddit Profile (JSON详细格式)+### 自定义LLM提示词-```json-[- {- "realname": "Test User",- "username": "test_user_123",- "bio": "A test user for validation",- "persona": "Test User is an enthusiastic participant in social discussions.",- "age": 25,- "gender": "male",- "mbti": "INTJ",- "country": "China",- "profession": "Student",- "interested_topics": ["Technology", "Education"]- }-]-```+主要提示词文件:+- 本体生成: `app/services/ontology_generator.py` → `ONTOLOGY_SYSTEM_PROMPT`+- 人设生成: `app/services/oasis_profile_generator.py` → `_build_individual_persona_prompt`+- 配置生成: `app/services/simulation_config_generator.py` → `_generate_time_config`-| 字段 | 类型 | 必填 | 说明 |-|------|------|------|------|-| `realname` | string | 是 | 真实姓名 |-| `username` | string | 是 | 用户名 |-| `bio` | string | 是 | 简介(最大150字符) |-| `persona` | string | 是 | 详细人设描述 |-| `age` | int | 否 | 年龄 |-| `gender` | string | 否 | 性别 |-| `mbti` | string | 否 | MBTI人格类型 |-| `country` | string | 否 | 国家 |-| `profession` | string | 否 | 职业 |-| `interested_topics` | array | 否 | 感兴趣话题列表 |+### 调试技巧----+1. **查看日志**:+ ```bash+ tail -f logs/$(date +%Y-%m-%d).log+ ```-## 7. OASIS平台动作类型--### Twitter可用动作--| 动作 | 说明 |-|------|------|-| `CREATE_POST` | 发布推文 |-| `LIKE_POST` | 点赞推文 |-| `REPOST` | 转发推文 |-| `FOLLOW` | 关注用户 |-| `QUOTE_POST` | 引用转发 |-| `DO_NOTHING` | 不执行动作 |--### Reddit可用动作--| 动作 | 说明 |-|------|------|-| `CREATE_POST` | 发布帖子 |-| `CREATE_COMMENT` | 发表评论 |-| `LIKE_POST` | 点赞帖子 |-| `DISLIKE_POST` | 踩帖子 |-| `LIKE_COMMENT` | 点赞评论 |-| `DISLIKE_COMMENT` | 踩评论 |-| `SEARCH_POSTS` | 搜索帖子 |-| `SEARCH_USER` | 搜索用户 |-| `TREND` | 查看热门 |-| `REFRESH` | 刷新推荐 |-| `FOLLOW` | 关注用户 |-| `MUTE` | 屏蔽用户 |-| `DO_NOTHING` | 不执行动作 |-----+2. **测试API**:+ ```bash+ # 使用httpie+ http POST localhost:5001/api/graph/ontology/generate \+ simulation_requirement="测试需求"+ ```-# 实体设计原则+3. **调试模式**:+ ```python+ # 在代码中添加断点+ import pdb; pdb.set_trace()+ ```-本系统专为社会舆论模拟设计,实体必须是:+----**可以是:**-- 具体的个人(有名有姓)-- 注册的公司、组织、机构-- 媒体机构-- 政府部门-- 高校、NGO等+## 常见问题-**不可以是:**-- 抽象概念(如"技术"、"创新")-- 情绪、观点、趋势-- 泛指的群体(如"用户"、"消费者")+### Q1: Zep API调用失败-这是因为后续需要模拟各实体对舆论的反应和传播,抽象概念无法参与这种模拟。+**原因**: API密钥错误或网络问题----+**解决**:+1. 检查`.env`中的`ZEP_API_KEY`+2. 测试Zep连接:+ ```python+ from zep_cloud.client import Zep+ client = Zep(api_key="your-key")+ client.graph.list()+ ```+3. 查看日志中的详细错误信息-# 项目状态流转+### Q2: LLM生成的JSON解析失败-```-created → ontology_generated → graph_building → graph_completed- ↓- failed-```+**原因**: LLM输出被截断或格式不正确----+**解决**:+- 系统已实现JSON修复逻辑+- 如仍失败,会自动回退到规则生成+- 可调整`temperature`参数降低随机性-# 运行模拟+### Q3: 模拟进程启动失败-准备完成后,进入模拟数据目录运行预设脚本:+**原因**: conda环境未激活或依赖缺失+**解决**:```bash-# 激活conda环境+# 确保在MiroFish环境中conda activate MiroFish-# 进入模拟目录-cd backend/uploads/simulations/sim_xxxx/--# 运行单平台模拟-python run_reddit_simulation.py --config simulation_config.json-# 或-python run_twitter_simulation.py --config simulation_config.json--# 运行双平台并行模拟(推荐)-python run_parallel_simulation.py --config simulation_config.json+# 检查OASIS依赖+pip install oasis-ai camel-ai```-### 脚本参数+### Q4: 内存不足++**原因**: 大型文档或大量实体-| 参数 | 说明 |-|------|------|-| `--config` | 配置文件路径(必填) |-| `--twitter-only` | 只运行Twitter模拟(仅parallel脚本) |-| `--reddit-only` | 只运行Reddit模拟(仅parallel脚本) |+**解决**:+1. 减小chunk_size+2. 限制entity_types数量+3. 使用更小的LLM模型+4. 增加系统内存-### 输出文件+### Q5: 文件上传失败-模拟运行后会生成:-- `twitter_simulation.db` - Twitter模拟数据库-- `reddit_simulation.db` - Reddit模拟数据库+**原因**: 文件大小超过限制或格式不支持-可使用SQLite工具查看模拟结果(帖子、评论、点赞等)+**解决**:+- 检查`Config.MAX_CONTENT_LENGTH`(默认50MB)+- 支持格式:PDF/MD/TXT+- 确保文件编码为UTF-8----# API调用重试机制+## 性能优化建议-**文件:** `app/utils/retry.py`+1. **并行处理**:+ - 人设生成并行数:`parallel_profile_count=5`+ - Zep批量上传:`batch_size=3`-为LLM等外部API调用提供自动重试功能,提高系统稳定性。+2. **缓存策略**:+ - 项目状态已持久化到文件+ - 任务状态使用内存缓存-## 重试策略+3. **容错重试**:+ - Zep API调用:3次重试+ - LLM API调用:3次重试-- **最大重试次数**:3次-- **退避策略**:指数退避(1s → 2s → 4s)-- **最大延迟**:30秒-- **随机抖动**:避免请求堆积+4. **日志管理**:+ - 日志文件自动轮转+ - 控制台只显示INFO+-## 使用方式+----**装饰器方式:**-```python-from app.utils.retry import retry_with_backoff+## 贡献指南-@retry_with_backoff(max_retries=3)-def call_llm_api():- return client.chat.completions.create(...)-```+### 代码规范-**客户端方式:**-```python-from app.utils.retry import RetryableAPIClient+1. 遵循PEP 8+2. 使用类型注解+3. 添加docstring+4. 编写单元测试-retry_client = RetryableAPIClient(max_retries=3)-result = retry_client.call_with_retry(some_function, arg1, arg2)-```+### 提交规范-**批量处理(单项失败不影响其他):**-```python-results, failures = retry_client.call_batch_with_retry(- items=entities,- process_func=generate_profile,- continue_on_failure=True-)```--## 已应用重试机制的模块--| 模块 | 说明 |-|------|------|-| `OasisProfileGenerator` | LLM生成Agent人设 |-| `SimulationConfigGenerator` | LLM生成模拟配置 |+feat: 添加新功能+fix: 修复bug+docs: 更新文档+refactor: 重构代码+test: 添加测试+```----# 依赖说明+## 许可证-```-# Flask框架-flask>=3.0.0-flask-cors>=4.0.0+MIT License-# Zep Cloud SDK-zep-cloud>=2.0.0+----# OpenAI SDK(LLM调用)-openai>=1.0.0+## 联系方式-# PDF处理-PyMuPDF>=1.24.0+- 项目地址: [GitHub链接]+- 问题反馈: [Issues链接]+- 技术文档: 见本README-# 环境变量-python-dotenv>=1.0.0+----# 数据验证-pydantic>=2.0.0+**最后更新**: 2025-12-02+**版本**: v1.0.0-# OASIS社交媒体模拟-oasis-ai>=0.1.0-camel-ai>=0.2.0-```