mechforge

MechForge AI

真正懂机械、敢说真话、能真算，“机械系苦逼在校生，用代码修补现实的缝隙，顺便造了个 MechForge AI 来骗自己‘我能拯救世界’（其实只是拯救我的 GPA）🔧🤖

Version License Python CI Docker GHCR Stars

📑 目录

✨ 核心特性

🤖 AI 对话模式

📚 知识库检索

🔧 CAE 工作台

🌐 Web 界面

🖥️ GUI 桌面应用

🔌 MCP 协议

🦙 本地模型管理

🚀 快速开始

💻 系统要求

安装

# 从 PyPI 安装 (推荐)
pip install mechforge-ai

# 完整安装（所有功能）
pip install mechforge-ai[all]

# 从源码安装
git clone https://github.com/yd5768365-hue/mechforge.git
cd mechforge
pip install -e ".[all]"

配置本地模型

方式 A: Ollama (推荐)

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 下载模型
ollama pull qwen2.5:1.5b

方式 B: GGUF 模型

# 下载 GGUF 文件
wget https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/qwen2.5-1.5b-instruct-q4_k_m.gguf \
  -O ./models/qwen2.5-1.5b.gguf

# 启动 GGUF 服务器
mechforge-model serve -m qwen2.5-1.5b.gguf

启动使用

# 查看可用模型
mechforge-model list

# 选择默认模型
mechforge-model select

# 启动 AI 对话 (终端)
mechforge

# 启动 GUI 桌面应用
mechforge-gui

# 启动知识库
mechforge-k

# 启动 CAE 工作台
mechforge-work

# 启动 CAE TUI 界面
mechforge-work --tui

# 启动 Web 界面
mechforge-web

📋 命令速查表

命令 说明 示例
mechforge 启动 AI 对话 直接运行进入交互模式
mechforge-gui 启动 GUI 桌面应用 图形化界面
mechforge-k 启动知识库 mechforge-k search "关键词"
mechforge-work 启动 CAE 工作台 mechforge-work demo
mechforge-work --tui 启动 CAE TUI 界面 交互式终端界面
mechforge-web 启动 Web 界面 访问 http://localhost:8080
mechforge-model 模型管理 mechforge-model list

📦 Docker 部署

提供多种镜像变体，支持 linux/amd64 和 linux/arm64 平台。

快速启动

# 方式一：使用启动脚本
./docker-start.sh start           # Linux/macOS
docker-start.bat start            # Windows

# 方式二：Docker Compose (推荐)
git clone https://github.com/yd5768365-hue/mechforge.git
cd mechforge
cp .env.example .env
docker-compose --profile full up -d

# 方式三：直接拉取镜像运行
docker pull ghcr.io/yd5768365-hue/mechforge:latest
docker run -it --rm ghcr.io/yd5768365-hue/mechforge:latest

镜像变体

镜像 大小 描述
ghcr.io/yd5768365-hue/mechforge:latest ~800MB 完整版（推荐）
ghcr.io/yd5768365-hue/mechforge-ai:latest ~200MB AI 对话模式
ghcr.io/yd5768365-hue/mechforge-rag:latest ~500MB 知识库 RAG 模式
ghcr.io/yd5768365-hue/mechforge-work:latest ~400MB CAE 工作台模式
ghcr.io/yd5768365-hue/mechforge-web:latest ~300MB Web 服务模式

Docker Compose 启动模式

docker-compose --profile ai up -d      # AI 对话
docker-compose --profile rag up -d     # 知识库
docker-compose --profile work up -d    # CAE 工作台
docker-compose --profile web up -d     # Web 服务
docker-compose --profile full up -d    # 完整版 (推荐)

环境变量

变量 默认值 说明
OLLAMA_URL http://ollama:11434 Ollama 服务地址
OLLAMA_MODEL qwen2.5:1.5b 默认使用的模型
LOG_LEVEL INFO 日志级别
WEB_PORT 8080 Web 服务端口

📖 详细文档请参阅 Docker 部署指南

📖 使用指南

AI 对话示例

$ mechforge

[MechForge] > 计算一个长100mm的悬臂梁挠度，截面10x10mm，受力1000N

AI: 我来为您计算这个悬臂梁的挠度...

使用工具: calculate_cantilever_deflection
参数: {"length": 100, "force": 1000, "width": 10, "height": 10}

结果: 最大挠度为 0.0254 mm

计算公式: δ = FL³ / (3EI)
其中:
- F = 1000 N
- L = 100 mm
- E = 210000 MPa (钢材)
- I = 833.33 mm⁴

📚 知识库高级配置

后端选择

MechForge AI 支持两种知识库后端：

后端 特点 适用场景
local 轻量级，无需外部服务 Markdown/TXT 文档，快速部署
ragflow 高级文档解析能力 PDF/图片/表格，OCR 需求

配置方式

编辑 config.yaml：

knowledge:
  # 选择后端: local | ragflow
  backend: "local"

  # 本地后端配置
  path: "./knowledge"

  # RAGFlow 后端配置（当 backend: ragflow 时生效）
  ragflow:
    url: "http://localhost:9380"
    api_key: "your-api-key"
    kb_id: "your-kb-id"

🔧 RAGFlow 集成指南

RAGFlow 是一个开源的 RAG 引擎，提供高级文档解析能力：

Step 1: 部署 RAGFlow

# 克隆 RAGFlow 仓库
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

# 修改 .env（可选，使用稳定版本）
echo "RAGFLOW_IMAGE=infiniflow/ragflow:v0.15.0" > .env

# 启动服务（CPU 版本）
docker compose -f docker-compose.yml up -d

# 或使用 GPU 版本
# docker compose -f docker-compose-gpu.yml up -d

启动后访问 http://localhost:9380，默认账号 ragflow / infiniflow。

Step 2: 创建知识库

  1. 登录 RAGFlow 界面
  2. 点击 Knowledge Base → Create Knowledge Base
  3. 输入知识库名称（如 mechanical）
  4. 选择解析方法：
    • General: 通用文档
    • Manual: 手册类文档
    • Law: 法律法规
    • Paper: 学术论文
    • Book: 书籍
    • Table: 表格类文档
  5. 上传文档并等待解析完成

Step 3: 获取 API 凭证

  1. 点击右上角 Settings → API Keys
  2. 创建新的 API Key
  3. 记录 API Key 和 Knowledge Base ID

Step 4: 配置 MechForge AI

编辑 config.yaml：

knowledge:
  backend: "ragflow"
  ragflow:
    url: "http://localhost:9380"
    api_key: "ragflow-xxxxxxxxxxxx"
    kb_id: "kb_xxxxxxxxxxxx"

Step 5: 使用知识库

from mechforge_knowledge import get_backend_from_config

# 获取配置的后端
backend = get_backend_from_config()

# 检查健康状态
is_healthy = await backend.health_check()

# 检索知识库
results = await backend.search("轴承选型方法", top_k=5)
for result in results:
    print(f"来源: {result.source}")
    print(f"内容: {result.content}")
    print(f"相关度: {result.score}")

RAGFlow 常见问题

Q: RAGFlow 启动失败

# 检查端口占用
netstat -tlnp | grep 9380

# 查看日志
docker logs ragflow-server

# 重启服务
docker compose restart

Q: 文档解析慢

Q: 检索结果不准确

CAE 分析示例

$ mechforge-work

[MechBot] > /demo
✓ 悬臂梁示例已加载

[MechBot] > /mesh --size=2.0
✓ 网格生成完成: 12345 节点, 6789 单元

[MechBot] > /solve
✓ 求解完成
  最大位移: 0.025396 mm
  最大应力: 125.60 MPa

[MechBot] > /show vonmises
[显示应力云图...]

使用 CalculiX API 远程求解

# 设置 API 端点
[MechBot] > /api https://your-calculix-api.com

# 使用 API 求解
[MechBot] > /solve --api

Web 界面

访问 http://localhost:8080 使用 Web 界面：

🏗️ 技术架构

┌─────────────────────────────────────────────────────────────┐
│                      MechForge AI v0.4.1                    │
├──────────────┬──────────────┬──────────────┬────────────────┤
│  AI 对话     │  知识库      │  CAE 工作台  │  Web 界面      │
├──────────────┼──────────────┼──────────────┼────────────────┤
│ LLM Client   │ RAG Engine   │ Gmsh 4.15+   │ FastAPI        │
│ MCP Tools    │ BM25/Rerank  │ CalculiX     │ WebSocket      │
│ Streaming    │ ChromaDB     │ PyVista      │ Security       │
├──────────────┴──────────────┴──────────────┴────────────────┤
│              GUI 桌面应用 (PySide6 + 科幻主题)               │
├─────────────────────────────────────────────────────────────┤
│              Core (Config / MCP / Local Model Manager)       │
├─────────────────────────────────────────────────────────────┤
│  🦙 Ollama  │  📦 GGUF HTTP  │  🔧 MCP Servers               │
└─────────────────────────────────────────────────────────────┘

📦 依赖分组

# 基础功能 (AI Chat)
pip install mechforge-ai

# GUI 桌面应用 (+PySide6)
pip install mechforge-ai[gui]

# CAE 功能 (+Gmsh +CalculiX +PyVista)
pip install mechforge-ai[work]

# RAG 功能 (+ChromaDB +Sentence-Transformers)
pip install mechforge-ai[rag]

# Web 界面 (+FastAPI +WebSocket)
pip install mechforge-ai[web]

# 完整功能 (所有依赖)
pip install mechforge-ai[all]

🔧 故障排除

常见问题

Q: 启动时提示 “命令未找到”

# 确保安装成功并添加到 PATH
pip install --upgrade mechforge-ai
# 或重新安装
pip install --force-reinstall mechforge-ai

Q: CAE 功能无法使用

# 检查 CAE 环境
python check_cae_env.py

# 安装 CAE 依赖
pip install mechforge-ai[work]

Q: 模型加载失败

# 检查 Ollama 是否运行
ollama list

# 或检查 GGUF 文件路径
mechforge-model list

Q: Web 界面无法访问

# 检查端口是否被占用
mechforge-web --port 8081

# 或使用不同的主机
mechforge-web --host 0.0.0.0

🛠️ 开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码检查
ruff check .
black --check .
mypy mechforge_*/

# 构建文档
python scripts/build_docs.py

# 构建包
python scripts/build_package.py

📂 项目结构

mechforge_ai/
├── mechforge_core/            # 核心模块
│   ├── config.py              # Pydantic 配置
│   ├── cache.py               # 多级缓存系统
│   ├── database.py            # SQLite 数据库
│   ├── logger.py               # 结构化日志
│   ├── security.py             # 安全工具
│   ├── mcp/                    # MCP 协议实现
│   ├── gguf_server.py          # GGUF HTTP 服务器
│   └── local_model_manager.py  # 本地模型管理
├── mechforge_ai/              # AI 对话
│   ├── llm_client.py          # LLM 客户端
│   ├── terminal.py            # 终端界面
│   ├── rag_engine.py          # RAG 引擎
│   └── model_cli.py           # 模型 CLI
├── mechforge_knowledge/       # 知识库
│   ├── cli.py                 # 知识库 CLI
│   ├── lookup.py              # 查询引擎
│   └── rag.py                 # RAG 实现
├── mechforge_work/            # CAE 工作台
│   ├── work_cli.py            # CAE CLI
│   ├── mesh_engine.py         # Gmsh 网格引擎
│   ├── solver_engine.py       # CalculiX 求解器
│   ├── viz_engine.py          # PyVista 可视化
│   └── cae_core.py            # CAE 核心
├── mechforge_web/             # Web 界面
│   ├── api.py                 # API 路由
│   ├── main.py                # FastAPI 应用
│   ├── middleware.py          # 安全中间件
│   └── security_config.py     # 安全配置
├── mechforge_theme/           # 主题组件
│   ├── colors.py              # 颜色定义
│   └── components.py          # UI 组件
├── mechforge_gui_ai/          # GUI 桌面应用 (PySide6)
│   ├── app.py                 # 应用入口
│   ├── main_window.py         # 主窗口
│   ├── theme.py               # 终端风格主题
│   ├── dialogs.py             # 配置对话框
│   └── build_gui.py           # 打包脚本
├── docs/                      # 文档
├── tests/                     # 测试
├── examples/                  # 示例
└── scripts/                   # 脚本

🤝 贡献

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

  1. Fork 仓库
  2. 创建特性分支 (git checkout -b feature/amazing)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 推送分支 (git push origin feature/amazing)
  5. 创建 Pull Request

📄 许可证

本项目采用 MIT License 开源。

🙏 致谢

感谢以下开源项目：

📞 联系我们

📝 更新日志

v0.4.1 (2026-03-06)

✨ 新特性

🔧 改进

🐛 修复

v0.4.0 (2026-03-05)

✨ 新特性

🔧 改进

🐛 修复

v0.3.0 (2025-12-15)

v0.2.0 (2025-11-01)

v0.1.0 (2025-10-01)

🚀 后续开发目标

v0.5.0 (计划中)

v0.6.0 (敬请期待)

🎯 知识驱动，智能进化

v0.6.0 将是一个重要里程碑，核心目标是构建一个持续学习、不断进化的机械工程知识库系统。

核心特性：

知识库建设计划：

Made with ❤️ for Mechanical Engineers

v0.6.0 敬请期待 🚀

This site is open source. Improve this page.