Mock Test

Pymock MVP - 人工智能模拟考试平台

一个基于Docker Compose的最小可行性产品（MVP）应用，利用LangChain、LangGraph、模型上下文协议（MCP）以及集成Gemma2的Ollama，实现AI驱动的模拟考试生成。

🎯 特点

• 基于人工智能的考试生成通过Ollama使用Gemma2进行智能问题生成
• 多智能体架构由LangGraph协调的用于课程大纲分析、问题生成和反馈的智能体
• 真实的考试体验适当的时机、部分划分、负向计分以及导航
• 综合反馈按主题分析，配备快速通道与深度掌握学习计划
• 聊天集成支持WhatsApp/Telegram的自然语言考试生成
• 课程大纲-真实内容问题与最新的考试模式和大纲相契合

🏗️ 建筑学

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Flask API     │    │   LangGraph     │    │     Ollama      │
│   (FastAPI)     │◄──►│   Workflow      │◄──►│   (Gemma2)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐    ┌─────────────────┐
│    MongoDB      │    │     Redis       │
│   (Database)    │    │    (Cache)      │
└─────────────────┘    └─────────────────┘

🚀 快速入门

先决条件

• Docker（20.10+）
• Docker Compose（1.29+）
• 为容器提供4GB+ RAM
• 10GB+的磁盘空间用于存储模型和数据

1. 克隆并设置

# Clone the repository files into your project directory
mkdir pymock-mvp
cd pymock-mvp

# Copy all the provided files into appropriate locations
# (Use the artifacts provided above)

2. 创建目录结构

mkdir -p app/agents app/database app/services logs
touch app/__init__.py app/agents/__init__.py app/database/__init__.py app/services/__init__.py

3. 启动应用程序

# Make startup script executable
chmod +x startup.sh

# Run the startup script (recommended)
./startup.sh

# OR start manually
docker-compose up -d

4. 验证安装

# Check health
curl http://localhost:5000/health

# Generate a test exam
curl -X POST http://localhost:5000/api/exam/generate \
     -H "Content-Type: application/json" \
     -d '{
       "exam_type": "JEE_MAIN",
       "subject_areas": ["Mathematics", "Physics"],
       "difficulty": "medium",
       "duration": 60,
       "num_questions": 10
     }'

📡 API 接口点

核心考试API

聊天集成

请求示例

生成考试（题目/试卷）

{
  "exam_type": "NEET",
  "subject_areas": ["Physics", "Chemistry", "Biology"],
  "difficulty": "medium",
  "duration": 180,
  "num_questions": 50,
  "negative_marking": true
}

提交考试

{
  "answers": {
    "Q001": "A",
    "Q002": "B",
    "Q003": "C"
  },
  "time_taken": {
    "Q001": 45,
    "Q002": 60,
    "Q003": 30
  }
}

聊天生成

{
  "message": "Generate a medium difficulty JEE Main mock test",
  "user_id": "user123"
}

🤖 代理架构

1. 课程大纲代理

• 分析考试大纲和主题权重
• 提供与蓝图一致的内容结构
• 缓存课程大纲数据以提高效率

2. 代理纸张（或：纸质代理，根据上下文具体含义可能有所不同）

• 根据课程大纲要求生成问题
• 保持难度分布
• 创建逼真的问题格式

3. 模拟代理

• 组装完整的考试结构
• 处理章节、计时和导航
• 创建考试会话

4. 反馈代理

• 分析多个维度下的性能表现
• 生成可实施的改进计划
• 提供时间管理见解

🗃️ 数据库模式

考试合集

{
  "exam_id": "uuid",
  "exam_type": "JEE_MAIN",
  "title": "JEE Main Mock Test",
  "duration": 180,
  "questions": {...},
  "sections": {...},
  "created_at": "ISO_DATE"
}

投稿收集

{
  "submission_id": "uuid",
  "exam_id": "uuid",
  "student_id": "string",
  "answers": {...},
  "performance": {...},
  "submitted_at": "ISO_DATE"
}

⚙️ 配置

环境变量

# Database
MONGODB_URI=mongodb://pymock:pymock123@mongodb:27017/pymock?authSource=admin
REDIS_URL=redis://redis:6379

# AI Model
OLLAMA_BASE_URL=http://ollama:11434
MODEL_NAME=gemma2:2b

# Application
FLASK_DEBUG=1
MAX_QUESTIONS_PER_EXAM=100
DEFAULT_EXAM_DURATION=180

支持的考试类型

• NEET（Not in Education, Employment, or Training）通常被翻译为“不工作、不学习、不培训”的人群，或者更通俗地理解为“啃老族”或“尼特族”。这个术语用来描述那些既不上学、也不工作、更不接受培训，主要依赖家庭经济支持生活的人群医学入学考试（物理、化学、生物）
• JEE_MAIN（印度联合入学考试主考试）工程学入学考试（数学、物理、化学）
• SSC_CGL（国家公务员联合考试）政府职位（4个部分）

🔍 监控和日志

查看日志

# Application logs
docker-compose logs -f pymock-api

# Ollama logs
docker-compose logs -f ollama

# Database logs
docker-compose logs -f mongodb

健康监测

# Check service health
curl http://localhost:5000/health

# Monitor resource usage
docker-compose top

🛠️ 开发

本地开发环境设置

1. 安装Python依赖项

pip install -r requirements.txt

1. 运行单个服务

# Start only infrastructure
docker-compose up -d mongodb redis ollama

# Run Flask app locally
cd app
python main.py

1. 测试

# Run tests (when implemented)
pytest

# Manual API testing
python -m pytest tests/ -v

添加新的考试类型

1. 更新 config.py 采用新的考试配置
2. 在课程大纲代理中添加大纲模板
3. 使用新题型进行测试

扩展代理

1. 在（系统/环境中）创建新代理 app/agents/
2. 添加到工作流中 agents/workflow.py
3. 根据需要更新API终端点

🚨 故障排除

常见问题

未找到Ollama模型

# Manually pull model
curl -X POST http://localhost:11434/api/pull -d '{"name": "gemma2:2b"}'

MongoDB 连接失败

# Check MongoDB logs
docker-compose logs mongodb

# Reset MongoDB data
docker-compose down -v
docker-compose up -d mongodb

Redis 连接问题

# Test Redis connection
docker-compose exec redis redis-cli ping

# Clear Redis cache
docker-compose exec redis redis-cli FLUSHALL

性能优化

1. 扩展服务

# In docker-compose.yml
pymock-api:
  deploy:
    replicas: 3

1. 优化模型使用

• 使用更小的模型进行开发
• 实现请求批处理
• 添加响应缓存

1. 数据库优化

• 添加适当的索引
• 实现连接池
• 使用读取副本进行扩展

🔒 安全考量

• 更改生产环境中的默认密码
• 使用环境特定的配置
• 为API端点实现速率限制
• 为敏感操作添加身份验证
• 基于安全令牌的考试访问

📈 规模化生产

水平扩展

# docker-compose.prod.yml
version: '3.8'
services:
  pymock-api:
    deploy:
      replicas: 3
    
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

微服务架构

• 将代理拆分为单独的服务
• 使用消息队列进行通信
• 实施断路器机制
• 添加服务发现功能

🤝 贡献

1. 为仓库创建分支
2. 创建特性分支
3. 为新功能添加测试
4. 提交拉取请求

📄 许可证

此项目采用MIT许可证授权——详情请参阅LICENSE文件。

🎯 路线图/路线规划

• \[ \] WhatsApp/Telegram机器人集成
• \[ \] 实时监考功能
• \[ \] 高级分析仪表板
• \[ \] 多语言支持
• \[ \] 移动应用（React Native）
• \[ \] 认证合作伙伴关系
• \[ \] 机构管理功能

______________________________________________________________________

准备用AI彻底改变备考方式！ 🚀（火箭/快速上升/加速的符号，具体含义需结合上下文）

______________________________________________________________________

🚀 快速入门

# Clone repo
git clone 
cd pymock

# Build and start all services
docker-compose up -d

# Wait 2-5 minutes for Ollama to pull and load gemma2:2b
# Check if model is ready:
curl http://localhost:11434/api/tags

# Check app health:
curl http://localhost:5000/health

✅ 首次运行触发器 model-init 服务——它拉动（或吸引） gemma2:2b 自动导入到Ollama中。

______________________________________________________________________

🌐 核心端点

______________________________________________________________________

🐳 Docker 服务概览

|

• ollama_data 持久卷：
• mongodb_data → 存储下载的模型
• redis_data → 数据库文件

______________________________________________________________________

→ 缓存持久化

建筑学 \[Flask 应用\] → \[代理工作流\] ↓ \[MCP客户端调用\] ↓ \[MCP 服务器（FastAPI）\] ↓ \[MongoDB\] \[Redis\] \[内部逻辑\] ↓ \[返回结构化JSON\] ↓

\[大型语言模型利用数据生成问题/反馈\]

.
├── app/
│   ├── agents/           # SyllabusAgent, PaperAgent, MockAgent, FeedbackAgent
│   ├── database/         # MongoDBClient.py
│   ├── services/         # CacheService.py
│   └── __init__.py
├── logs/                 # App logs (mounted from host)
├── config.py             # Loads env vars (OLLAMA_BASE_URL, REDIS_URL, etc.)
├── app.py                # Flask app + routes
├── Dockerfile            # Builds pymock-api image
└── docker-compose.yml    # Defines all services & networking

./mcp_server/
├── Dockerfile
├── main.py          # FastAPI/MCP server
├── tools/
│   ├── syllabus_tool.py
│   ├── question_tool.py
│   ├── feedback_tool.py
│   └── __init__.py
├── models.py        # Pydantic models for MCP
└── requirements.txt

______________________________________________________________________

📁 代码结构

⚙️ 环境变量 docker-compose.yml 设定于

# Flask
FLASK_ENV=development
FLASK_DEBUG=1

# Database
MONGODB_URI=mongodb://pymock:pymock123@mongodb:27017/pymock?authSource=admin

# Cache
REDIS_URL=redis://redis:6379

# AI / Ollama
OLLAMA_BASE_URL=http://ollama:11434
MODEL_NAME=gemma2:2b

→ 传递给 Flask 应用： app/agents/workflow.py ✅ 您在（某地/某机构）的代理 /api/generate 将使用这些来调用Ollama的

______________________________________________________________________

端点。

🧠 关键模块 services/cache_service.py

➤

• create_secure_token(exam_params) 处理 Redis 操作：
• validate_secure_token(token) → 返回 UUID，并在 Redis 中存储，设置 TTL（生存时间）
• cache_exam(exam_id, exam_data) → 获取并验证考试参数
• health_check() → 缓存考试JSON

→ 向 Redis 发送 ping 请求 database/mongodb.py

➤

• store_exam()MongoDB 封装器： get_exam()
• store_submission()， get_feedback()
• health_check() ， ping → 跑步

命令 agents/workflow.py

➤

workflow = create_exam_workflow()  # Chains 4 agents

result = workflow.invoke({
    "exam_type": "NEET",
    "subject_areas": ["Biology"],
    "difficulty": "medium",
    "duration": 180
})

基于LangChain的代理管道： gemma2:2b → 用途

______________________________________________________________________

通过Ollama进行问题和反馈的生成。

🧪 示例API使用方法

curl -X POST http://localhost:5000/api/exam/generate \
  -H "Content-Type: application/json" \
  -d '{
    "exam_type": "JEE Main",
    "subject_areas": ["Physics", "Maths"],
    "difficulty": "hard",
    "duration": 180,
    "num_questions": 25
  }'

1. 生成考试（或：出题/制作试卷）

curl -X POST http://localhost:5000/api/chat/generate-exam \
  -H "Content-Type: application/json" \
  -d '{"message": "Generate a 30-min Biology mock for NEET"}'

2\. 基于聊天的应用考试（例如，针对WhatsApp） {"exam_url": "/exam/abc123-xyz789", "expires_in": "24 hours"}

→ 返回安全链接：

curl http://localhost:5000/exam/abc123-xyz789

3\. 解析令牌（或：解决令牌问题）

______________________________________________________________________

→ 触发生成考试并返回完整的考试对象。

🛠️ 开发小贴士

docker-compose build pymock-api
docker-compose up -d

代码更改后的重建

docker-compose logs -f pymock_api     # Flask app
docker-compose logs -f ollama         # LLM server
docker-compose logs pymock_model_init # Model pull status

查看日志

curl http://localhost:11434/api/tags
# Should include: { "name": "gemma2:2b", ... }

验证模型已加载

curl -f http://localhost:5000/health
# Returns 200 if MongoDB, Redis, and app are healthy

______________________________________________________________________

健康检查

🧹 清理

docker-compose down -v

______________________________________________________________________

停止容器并删除卷（模型、数据库、缓存）：

• 🛑 故障排除 模型加载失败？ model-init → 检查

  docker-compose run --rm pymock_model_init

• 日志。如果失败，请手动运行： LLM超时？ phi3:mini→ 增加代理的超时时间或尝试使用更小的模型，如
• . 连接被拒绝？ up 等待60秒后
• — Ollama需要时间来加载模型。 缓存/数据库无法连接？mongodb→ 验证环境变量中的服务名称是否与 Docker Compose 服务名称匹配（ redis， ollama，

______________________________________________________________________

）。

• ✅ 系统要求
• Docker & Docker Compose
• 至少需要8GB内存（Ollama + gemma2:2b占用内存较大）
• Python 3.9+（用于容器外的本地开发）

______________________________________________________________________

~5GB磁盘空间用于模型+数据库 gemma2:2b 💡 提示：为了加快迭代速度，考虑进行交换 phi3:mini 和，与 llama3:8b-instruct-q4_K_M 或者

______________________________________________________________________

如果你的内存更大——生成考试题目的推理能力会更强。

• 如果你需要的话，请告诉我： Makefile A.
• 对于常用命令 devcontainer.json
• VS Code .env 样本
• 用于本地非Docker开发的文件

更换为不同Ollama模型的说明