HAGAMEAI 开源项目最佳实践教程

1. 项目介绍

HAGAMEAI 是一个基于 FastAPI 构建的开源项目，旨在为人类对抗 AI 游戏场景、高级认知建模以及基于大型语言模型（LLM）的服务提供一个模块化、可扩展且安全的 API。该项目使用最新的技术栈，包括异步框架、数据库、ORM、任务队列等，以支持游戏定义、用户认证、AI 引擎、LLM 集成服务等功能。

2. 项目快速启动

环境准备

确保安装了 Python 3.10 或更高版本。安装项目依赖：

uv pip install -r pyproject.toml

复制 .env.example 文件为 .env，并填写配置信息：

cp .env.example .env

配置文件中需要包含以下变量：

• DATABASE_URL: PostgreSQL 异步 URL（例如 postgresql+asyncpg://user:password@localhost:5432/hagame_db）
• SECRET_KEY: JWT 密钥
• ALGORITHM: JWT 算法（默认：HS256）
• ACCESS_TOKEN_EXPIRE_MINUTES: JWT 令牌过期时间（默认：60分钟）

运行应用

使用以下命令启动应用：

uvicorn main:app --reload

启动后，可以通过以下地址进行健康检查：

http://localhost:8000/

API 文档可以通过以下地址访问：

http://localhost:8000/docs

3. 应用案例和最佳实践

用户认证与 Profile 管理

• 注册新用户：POST /auth/register
• 获取 JWT 令牌：POST /auth/login
• 获取当前用户信息：GET /auth/me（需 JWT 认证）
• 获取或更新用户 Profile：GET/PUT /users/me/profile（需 JWT 认证）
• 获取或更新认知 Profile：GET/PUT /users/me/cognitive-profile（需 JWT 认证）

游戏核心框架

• 列出或创建游戏定义：GET/POST /games/definitions
• 获取游戏定义详情：GET /games/definitions/{game_def_id}
• 创建新游戏实例：POST /games/instances
• 获取游戏实例详情：GET /games/instances/{instance_id}
• 列出当前用户所有游戏实例：GET /games/my-instances

AI 引擎

• 列出所有 AI 模型：GET /ai-models/
• 创建新 AI 模型：POST /ai-models/
• 获取 AI 模型详情：GET /ai-models/{model_id}

LLM 集成服务

• 调用 LLM API：POST /llm/call
• 列出当前用户所有 LLM 调用日志：GET /llm/logs

4. 典型生态项目

HAGAMEAI 作为一个游戏与 AI 结合的开源项目，可以与以下生态项目结合：

• Celery：用于异步任务处理，如 AI 模型训练、批预测等。
• Prometheus 和 Grafana：用于性能监控和可视化。
• ELK Stack 或 Grafana Loki：用于日志管理和分析。
• Docker 和 Docker Compose：用于容器化和部署。

通过以上最佳实践，开发者可以更好地理解 HAGAMEAI 项目，并高效地应用于实际开发中。