格斗游戏AI助手

MKMChat（真人快打移动助理）

MKMChat是Mortal Kombat Mobile的高级本地第一AI助手和模型上下文协议（MCP）服务器。它结合了高性能的Python搜索后端、高级RAG检索、本地Ollama LLM执行和令人惊叹的Laravel+Livewire web界面。

🌟 主要特点

• ⚔️ 智能团队建议：组装自定义的3个角色团队组合，包括角色类别分析、被动协同评级和为每个插槽推荐的特定设备卡。
• 📖 机械解释流程：解释复杂的游戏机制（例如。， 陷阱, 电源消耗, 遗忘)通过以结构化的格式生成清晰的定义和实用的作战建议。
• 💬 AI驱动的对话聊天：享受关于游戏机制、策略、等级排名和角色匹配的自然、情境感知的问答，并保持聊天历史记录。
• 🤖 推理模型支持：针对推理模型进行了动态优化，如 DeepSeek-R1 和 OpenAI o1/o3，为深度分析输出调整参数（上下文限制、温度）。
• 🛠️ MCP兼容工具服务器：通过模型上下文协议将丰富的游戏工具直接暴露给LLM客户端（如Claude Desktop、Cursor或AI代理）。
• 🎨 和谐的明暗模式：响应式、视觉优先的Laravel Livewire网络界面，具有玻璃形态设计、鲜艳的配色方案和无缝的暗/亮主题切换。

🧠 先进的混合RAG系统

检索管道已经过大幅升级，以确保最先进的相关性和准确性：

flowchart TD
    A[Game Data<br>TSV + TXT] --> B[Set-Aware Indexer]
    B --> C[Precise Chunking]
    C --> D[Text Normalization]
    D -- "sentence-transformers<br>all-MiniLM-L6-v2" --> E[Embeddings Cache<br>.rag_cache/]
    E --> F[Hybrid Retrieval<br>Semantic + Keyword Boost]
    F --> G[Ollama Assistant<br>Prompt Assembly]

1. 设置感知索引：索引器自动扫描字符集从属关系（例如。， {{Friendship}} 或 {{Brutality}} 标签）并注入相互交叉引用。检索一个项目自然会显示其集合伙伴的详细信息和名称（例如，检索 Baraka的部落厨师的喜悦 也表面 部落厨师的副业).
2. 真正的余弦相似性：向量嵌入（查询和文档向量）在创建和查询时在数学上是$L_2$标准化的。这些归一化向量的点积计算产生数学上精确的余弦相似性得分，严格限制在$[-1.0,1.0]$以内。
3. 混合检索（词汇关键字增强）：矢量嵌入(all-MiniLM-L6-v2)与专门的关键字匹配重新排序器相结合(_apply_keyword_boost()).角色名称、稀有等级和主要游戏术语的精确匹配会得到智能提升，确保在不损失关键字精度的情况下实现高语义召回。
4. 排版弹性：输入查询会自动规范化（例如，转换花引号 ’, “, ” 直接引用 ', ")以防止由不同键盘输入引起的匹配失败。
5. 颗粒状结块：术语表定义是逐术语分块的，游戏数据是逐行分块的。这避免了过大的搜索空间（“大块”），并提供了高度针对性的上下文片段。

🛠️ 建筑

• mkmchat/：Python核心包（异步FastAPI+Uvicorn HTTP服务器、MCP服务器实现和本地向量RAG系统）。
• webapp/：Laravel+Livewire web UI通过安全的 MkmApiService 包装。
• docker-compose.yml：全栈容器编排链接 ollama, python-api （内部网络），以及 webapp （主机暴露）。

🚀 高性能异步体系结构

Python API已完全迁移到完全异步的运行时堆栈：

• 异步Web核心：替换自定义 BaseHTTPRequestHandler 随着 快速API 在下面奔跑 Uvicorn.所有API路线(/suggest-team, /ask-question, /explain-mechanic, /chat, /health, /)异步运行(async def)而且不会堵塞。
• 并发验证：在Uvicorn的事件循环上并行执行多个并行请求。在负载测试下，执行5个并发API请求将产生与单个请求的延迟（约4.75秒）相匹配的墙锁执行总时间，从而实现 80%以上的并发延迟节省 与阻塞同步设计相比。
• 安全性和可靠性：实现了本地FastAPI异常处理程序，以实现精确的HTTP合约安全({"error": "details"} 输出格式）、基于客户端IP的自定义滑动速率限制依赖关系以及安全的API密钥认证报头。

🐳 使用Docker运行（推荐）

1） 准备环境文件

从项目根：

cp .env.docker.example .env.docker
cp webapp/.env.docker.example webapp/.env.docker

2） 配置您的环境

至少，在需要时确保这些匹配：

• MKM_API_KEY：后端和Laravel服务共享的用于身份验证的强随机字符串。
• OLLAMA_MODEL：要使用的默认模型标签（例如。， llama3.2:3b 或 deepseek-r1:14b-fit).
• MKM_DEBUG_PROMPTS：设置为 true 撰写详细的、经过全面编辑的法学硕士提示和回复 debug_llm.log 为了便于调整。

3） 启动堆栈

docker compose up -d --build

专用GPU/高VRAM调优（WSL和Linux）

部署高性能 DeepSeek-R1（14B） 针对GPU环境下的本地消费进行了优化的模型：

docker compose exec ollama sh -lc "cat > /tmp/Modelfile.deepseek14b-fit << 'EOF'
FROM deepseek-r1:14b
PARAMETER num_ctx 512
PARAMETER num_batch 32
PARAMETER num_predict 800
PARAMETER use_mmap true
PARAMETER temperature 0.2
EOF
ollama create deepseek-r1:14b-fit -f /tmp/Modelfile.deepseek14b-fit"

生成后，选择 deepseek-r1:14b-fit 在web应用程序模型选择器下拉列表中！

4） 端点

• 网络应用: http://localhost:8000
• Ollama接口: http://localhost:11434

注：Python API是Docker网络内部的(http://python-api:8080)并且不直接发布到主机以获得最大的容器级安全性。

5） 操作和日志

docker compose ps               # Check service status
docker compose logs -f python-api  # Live Python server logs
docker compose logs -f webapp      # Live Web UI logs
docker compose logs -f ollama      # Live Ollama inference logs
docker compose down             # Tear down all containers

💻 不使用Docker运行

1.Python API和RAG后端

请确保您已安装Python 3.10+：

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

pip install -e .
ollama pull llama3.2:3b
python -m mkmchat http

2.Laravel Web应用程序

确保已安装PHP 8.2+和Composer：

cd webapp
cp .env.example .env
composer install
npm install
npm run build
php artisan key:generate
php artisan migrate
php artisan serve

⚙️ 环境变量

核心变量(.env.docker)

🧪 测试

直接在容器内运行RAG和模型连接检查：

快速烟雾测试

docker compose exec webapp curl -X POST http://python-api:8080/explain-mechanic \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-mkm-api-key>" \
  -d '{"mechanic":"power drain","model":"llama3.2:3b"}'

Python RAG验证

要手动测试语义搜索质量、缓存验证和关键字增强，请执行以下操作：

# Inside the virtual environment
python tests/test_rag.py

📜 许可证

该项目根据 GNU GPL v3。请参阅 LICENSE 文件以获取详细信息。