Hugging Face's logo

Spaces:
sunye-cn
/
FateForge
Runtime error

App Files Community
FateForge / README.md
sunye-cn's picture
sunye-cn
add HF Small LLM Hackathon badges
afaae80 verified
preview code
|
Raw
History Blame Contribute Delete
9.3 kB
metadata 
title: FateForge
emoji: ☯
colorFrom: indigo
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: FateForge · 周易六爻 · 免登录 AI 命理

HF Spaces MIT Off the Grid Off-Brand UI Field Notes

FateForge

大衍之数五十,其用四十有九。缘主此来,所求何事?

FateForge 是一个把宋代水墨美学、周易六爻起卦、和小参数大语言模型三者揉在一起的 AI 命理 Web App。 缘主在首页写下心头的困惑,六枚铜钱经由一只静默的玄甲决定起伏;之后由本地 LLM(或 fallback 到本地卦象解读器)给出直白答案 + 卦象缘由 + 心法建议, 所有画面以水墨晕染、行楷、磬音铺陈,像在翻一本会呼吸的古书。

本项目是 Hugging Face 小型 LLM Hackathon 的参赛作品 —— 端到端跑在一个 2B 参数的 GGUF 量化模型 上, 向"小模型也能撑起有温度的 AI 应用"这个命题交卷。

🎥 一分钟演示

短视频: https://www.tiktok.com/@sunye9811/video/7651775539107073310

项目心得及项目复盘: https://huggingface.co/blog/build-small-hackathon/fateforge-local-llm

✨ 项目亮点

  • 免登录 · 完全本地化 — 输入、起卦、解读、历史都只存在你本机的浏览器里 (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 揭开 → 心法从模糊 → 清晰 → 底部"乾坤未定,且循其一"按钮 → 点击,卡片像被清风吹散,退回首页。

🚀 本地启动 

# 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