---
title: FateForge
emoji: ☯
colorFrom: indigo
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: FateForge · 周易六爻 · 免登录 AI 命理
---
# FateForge
> 大衍之数五十,其用四十有九。缘主此来,所求何事?
**FateForge** 是一个把宋代水墨美学、周易六爻起卦、和小参数大语言模型三者揉在一起的 AI 命理 Web App。
缘主在首页写下心头的困惑,**六枚铜钱**经由一只静默的玄甲决定起伏;之后由本地 LLM(或 fallback 到本地卦象解读器)给出**直白答案 + 卦象缘由 + 心法建议**,
所有画面以**水墨晕染、行楷、磬音**铺陈,像在翻一本会呼吸的古书。
本项目是 [Hugging Face 小型 LLM Hackathon](https://huggingface.co/blog/build-small-hackathon/fateforge-local-llm) 的参赛作品 —— 端到端跑在一个 **2B 参数的 GGUF 量化模型** 上,
向"小模型也能撑起有温度的 AI 应用"这个命题交卷。
---
## 🎥 一分钟演示
短视频:
项目心得及项目复盘:
---
## ✨ 项目亮点
- **免登录 · 完全本地化** — 输入、起卦、解读、历史都只存在你本机的浏览器里 (`localStorage`),不上传任何云端。
- **真·六爻起卦** — 三枚铜钱 (字=2, 背=3) 自下而上摇六次,生成 64 卦中的任意一卦,含动爻与变卦;卦名/卦辞/象传全部来自经典 (`require.md` 锁定)。
- **7 档吉凶** — 大吉 / 吉 / 中平偏吉 / 中平 / 中平偏凶 / 凶 / 大凶,每一档有专属语气与界面色温 (木 / 火 / 土 / 金 / 水 五行晕染)。
- **小模型优先** — 默认对接 `gemma-2-E2B-it-UD-Q4_K_XL.gguf` (2B 参数, GGUF 量化) 跑在本地 llama-server 上;离线时**自动降级**到 `interpret.py` 的本地卦象解读,仍能保留完整体验。
- **解读深度结合用户问题** — LLM Prompt 强制要求每句话锚定在缘主问题里的具体人物/事件/时间;本地降级会先识别问题主题 (事业/财运/感情/...),给出针对该维度的建议。
- **氛围即叙事** — 吉时页面是水墨金的"顺风"晕染;凶时是水墨红的"迷雾",中间一颗浅黄"遁其一"按钮像迷雾中的明灯;点击后按钮缓缓消失,蒙版揭开,心法一行行浮现 (clip-path 打字机揭示)。
- **全站双语** — 右上角 `EN / 中` 实时切换,所有界面文字 + 卦名 + 卦辞 + LLM 解读语种都跟语言走。
---
## 🖼️ 截图 / 录屏
| 缘起 | 窥机 (龟甲) | 窥机 (铜钱) | 破迷 (吉) | 破迷 (凶·遁其一) |
|:---:|:---:|:---:|:---:|:---:|
| 填写问题 | 点龟壳六次 | 铜钱翻转 | 卦象 + 心法 | 蒙版 + 按钮居中 |
短视频看 TikTok 链接,完整版心得看上面的 HF blog 链接。
---
## 🏗️ 架构
```
FateForge/
├── app.py # 入口: Gradio + FastAPI (HF Spaces Docker SDK)
├── Dockerfile # python:3.11-slim, EXPOSE 7860
├── requirements.txt # fastapi, uvicorn, httpx, pydantic, gradio
├── README.md # 你正在读的这篇
├── require.md # 需求规约: 64 卦表 / 7 档吉凶 / 文案质感 (锁版本)
└── fateforge/
├── __init__.py
├── config.py # 端口 / LLM 端点 / 路径
├── constants.py # HEXAGRAMS (64 卦), HEX_LEVELS (7 档), LLM Prompt
├── divination.py # 铜钱起卦 / 动爻 / 变卦 / 吉凶判定
├── llm.py # httpx 流式调用 llama-server (OpenAI 兼容)
├── interpret.py # 本地降级解读器: 按问题主题给建议
├── server.py # FastAPI: /api/cast/seed, /api/read (SSE 流式)
└── static/ # 前端 SPA
├── index.html # Vue 3 + Tailwind (CDN)
├── style.css # 1400+ 行水墨主题
├── app.js # 1270+ 行 Vue 状态机 + i18n
└── assets/ # 龟甲 / 铜钱 / 按钮底图 (LFS)
```
---
## 🔮 四关卡流转
```
缘起 (yuanqi) → 窥机 (kuiji) → 破迷 (pomi) → (回到首页)
│ │ │
输入问题 龟壳 × 6 卦象 + 心法
铜钱 × 3 (动画) 吉时: 直接显示
六爻成形 凶时: "前路晦暗" → 遁其一按钮
点击 → 燃烧动画 → 心法浮现
```
**吉/中平偏吉/大吉/中平** → 心法直接显示,底部出现"乾坤已定,且乘势启程"按钮 → 点击,模糊遮罩从左下角覆盖 → 返回首页。
**凶/中平偏凶/大凶** → 解卦正文先被蒙版隐去(只隐约看到字形)→ 中央出现浅黄色"遁其一"按钮 → 点击,清脆磬音响起,按钮 1.2s 缓慢消失 → 蒙版 1s 揭开 → 心法从模糊 → 清晰 → 底部"乾坤未定,且循其一"按钮 → 点击,卡片像被清风吹散,退回首页。
---
## 🚀 本地启动
```powershell
# 1. 安装依赖
pip install -r requirements.txt
# 2. (可选) 启动本地 LLM —— llama-server 默认监听 127.0.0.1:8080
# 没起 LLM 也能跑 —— 会自动降级到 interpret.py
llama-server -m gemma-2-E2B-it-UD-Q4_K_XL.gguf --port 8080
# 3. 启动 FateForge
python app.py
# → 访问 http://127.0.0.1:7860
```
### 环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
| `FATEFORGE_LLM_BASE_URL` | `http://127.0.0.1:8080` | llama-server 端点 |
| `FATEFORGE_LLM_MODEL` | `gemma-4-E2B-it-UD-Q4_K_XL.gguf` | 模型名 |
| `FATEFORGE_LLM_TIMEOUT` | `180` | 秒 |
| `FATEFORGE_HOST` | `0.0.0.0` | 监听地址 (HF Docker 必须 0.0.0.0) |
| `FATEFORGE_PORT` | `7860` | 端口 (HF 会注入 PORT, 自动同步) |
---
## 🤖 离线降级策略
为适配 HF Spaces 没有 GPU / llama-server 的现实, `/api/read` 在 LLM 不可达时会自动 fallback 到 `fateforge/interpret.py`:
1. **基础卦象描述** — 沿用经典 64 卦的卦辞/象传
2. **吉凶判定** — `HEX_LEVELS` 表内置 64 卦 × 7 档吉凶的预设
3. **问题主题识别** — `detect_topic()` 匹配"事业/财运/感情/出行/健康/学业/家宅"关键词
4. **主题化建议** — `build_remedy()` 开头用 `既然缘主所问的是事业/功名,那接下来:` 锚定到问题维度,给出 1-3 条具体可落地的建议
5. **流式输出** — 即便降级, 也按字流式输出,前端仍能看到"水墨渗字"效果
> 在 HF Spaces 上点开这个 Space, **LLM 离线也能完整体验**。
---
## 🎨 视觉与交互细节
- **五行晕染背景** — 缘起=木(淡青), 窥机=土(淡黄), 破迷=金/火(吉=金, 凶=火, 中平=土), 自渡=水(淡蓝)。每一页都是"从中心向外渐变淡"的水墨 radial-gradient。
- **字体** — 标题用 `Ma Shan Zheng` 行楷,正文用 `KaiTi` 楷体,英文 fallback 到 `Noto Serif`。配色统一为"焦茶墨色 + 浅黄/浅青/浅金晕染",白底调试模式可看宣纸纹理。
- **按钮** — 无边框,只有对应色系 (浅绿/浅黄/浅金) 的 4 层 box-shadow 呼吸光晕,悬停时呼吸加快。
- **凶局过渡** — 蒙版用 `backdrop-filter: blur(22px) saturate(120%)` + 红色内晕, 按钮消失后蒙版 1s 揭开, 心法从焦茶渐变深墨色。
- **手写体提示** — 用户疯狂连点龟壳时,前端数字不会变快 (避免视觉混乱),但后台 `totalTaps` 立即累加, 第 7 次弹水墨选择窗"缘主一卦只能摇六下哦"。
---
## 📚 64 卦数据来源
`require.md` 是项目的"圣经",锁版本维护:
- 卦序 (1-64) / 卦名 / 上下卦 / 卦辞 / 象传
- 7 档吉凶分类 (大吉/吉/中平偏吉/中平/中平偏凶/凶/大凶) 与判定理由
- 7 个等级对应的 LLM 语气与心法标签 (顺风借力 / 借风起帆 / 潜龙勿用 / 风雨欲来 等)
- 文案质感范例 (听天命 / 运在人为的句式与禁忌)
---
## 🛠️ 技术栈
| 层 | 选型 | 理由 |
|---|---|---|
| 后端 | FastAPI + uvicorn | 异步 SSE 流式输出对接前端 ink-seep 打字机 |
| LLM 通信 | httpx (async) | 流式 SSE, 兼容 OpenAI /v1/chat/completions |
| 前端框架 | Vue 3 (CDN) | 无构建步骤, 直接运行 |
| 样式 | Tailwind CDN + 自写水墨 CSS | 1400+ 行手写 .ink-* 风格 |
| 字体 | Google Fonts (Ma Shan Zheng, KaiTi, Noto Serif) | 宋代 / 现代 衬线感 |
| 部署 | Docker SDK on HF Spaces | 0.0.0.0:7860, ENV 注入 |
---
## 📜 License
MIT