Hackathon Advisor 是 Build Small Hackathon 的实时项目地图，也是给参赛者当“原创性教练”的小模型应用。打开它，先看到的是一张图谱，节点是 build-small-hackathon 组织下所有公开 Space。参赛者可以搜索整个赛场，查看项目聚类和任务（quest）证据，再打开 The Unwritten Almanac（未写就的年鉴），拿自己的点子和赛道上已有的作品比一比。
Build Small Hackathon 要求参赛者在 32B 参数上限内做项目，为身边的人解决一个具体问题，或者做一个让人愿意玩的 AI 原生体验，并提交 Space、演示视频和社交帖子。Hackathon Advisor 直接把这个赛场当数据源：每个公开 Space 都进到一张持续刷新的项目图谱里，顾问的每次回答都以这张共享地图为依据。
- 在线应用：build-small-hackathon-hackathon-advisor.hf.space
- 演示视频：YouTube
- 社交帖子：X
为什么做这个项目
参赛者一头扎进节奏很快的黑客松，手上的上下文其实很少：看着不错的点子可能早就挤满了人，冷门方向却没人看得见，奖项信息又散落在各个 README、标签和应用文件里。Hackathon Advisor 把赛场本身变成起点，让人看到项目堆在哪里、哪些作品彼此接近、它们看起来完成了哪些任务、新点子还有多少空间。
公开的黑客松组织本身就是一份现成的语料：Space、README、模型声明、应用文件、标签和演示视频。建好索引之后，参赛者能看清别人在做什么、用了什么方法、做出了什么。作者觉得这种可见性让线上黑客松有了类似 OpenAI Parameter Golf 挑战的创造力：开发过程中就能发现相邻的工作，认出重叠，借用有用的做法，把想法推到新领域，也能找到做相似问题的人，形成一个更快的开源反馈循环。
图谱是默认界面，因为地图本身就是证据。点 Open advisor 进顾问界面，它会基于同一份项目快照引用重叠项目、提出空白方向、给点子打分、起草构建计划，并导出会话证据。
功能
- 全屏 t-SNE 图谱：展示所有公开黑客松 Space，带 KMeans 聚类和最近邻连线。
- BM25 项目搜索：覆盖标题、slug、摘要、标签、声明的模型、聚类标签、任务证据、README 文本和声明的应用源文件。
- 筛选与详情：按聚类或任务筛选，看所选项目的摘要、Space 链接、标签、任务匹配和证据提示。
- 与图谱对话：“Ask the atlas” 抽屉能回答“谁完成的任务最多”“有哪些聚类”这类问题。它用的是基础版 MiniCPM5-1B 的原生工具调用，开着思考模式，推理过程实时流式显示在可折叠区块里；校验过的工具结果渲染成卡片，可以直接筛选或高亮地图，模型的文字回答则基于同一份结果的精简摘要。
- 刷新图谱：从 Space 后端刷新，校验通过的产物写进挂载的缓存目录，再原子替换到线上应用。
- 顾问工作区：点子对比、空白方向、评分印章、结合个人情况的计划、语音输入和可分享导出。
- 导出：界面上能导出构建笔记、Almanac 章节和页面 PNG；trace JSONL、演示包、提交材料包、LoRA 数据集和 LoRA 训练套件通过 API 提供。
工作原理
刷新时先给 build-small-hackathon 组织下的公开 Space 做快照，读每个 README 和声明的主应用文件，重建 EmbeddingGemma 项目索引；然后先解析官方的 track:*、sponsor:*、achievement:* 元数据标签，元数据没声明的部分再交给 MiniCPM 判断任务证据。仪表盘上有项目点、最近邻连线、聚类、任务覆盖、来源信息和刷新状态。
ADVISOR_CACHE_DIR 是存产物 的目录：在 Hugging Face Space 上指向挂载的 Storage Bucket，本地可以是 .cache/advisor-dashboard 这样的普通目录。每次刷新往 runs/{run_id}/ 下写 projects.json、project_index.json、dashboard.json、quest_analysis.json 和 manifest.json，再原子替换 latest.json。任务分析结果按项目缓存，缓存键包括推理 prompt 哈希、分类体系哈希、MiniCPM 模型 ID、适配器 ID/版本、本地适配器摘要和生成配置。
配了 ADVISOR_CACHE_DIR，应用可以启动每小时一次的定时刷新。提交版 Space 关掉了定时刷新，改用本地构建来更新挂载的 bucket，所以索引构建和任务分析不会在公开演示的运行时里跑。手动刷新和定时刷新都会抢 refresh.lock 锁，并在运行时发心跳；新一轮刷新校验失败，当前已校验的仪表盘就保持不动。
模型与数据
| 角色 | 模型 | 运行方式 | 说明 |
|---|---|---|---|
| 顾问 | openbmb/MiniCPM5-1B + hackathon-advisor-minicpm5-lora | ZeroGPU、Transformers、PEFT | 1.08B 的 OpenBMB 模型在每一轮决定调哪个工具；顾问文字由基于检索结果的确定性模板生成 |
| 任务分析 | 官方 Space 元数据 + openbmb/MiniCPM5-1B + hackathon-advisor-quest-minicpm5-lora | ZeroGPU、Transformers、PEFT | 信任 README 官方标签里声明的赛道、赞助奖和徽章，再用专用的 MiniCPM LoRA 把剩下的 README/应用文件证据分类成严格的任务 JSON |
| 项目检索 | embeddinggemma-300m-qat-q8_0-GGUF | 本地 llama.cpp 建索引、算查询向量 | 图谱和检索索引都通过 llama.cpp 用 GGUF 向量模型 |
| 语音输入 | nvidia/nemotron-speech-streaming-en-0.6b | ZeroGPU、NVIDIA NeMo ASR | 本地和线上用同一个 Nemotron 模型转写语音 |
MiniCPM 按官方示例加载（trust_remote_code=True、bfloat16，apply_chat_template 里设 enable_thinking=False），这样工具调用稳定，任务 JSON 也严格。整个运行时里最大的单个模型是约 1.08B 的 MiniCPM5-1B，所有模型加起来约 1.98B。
相关数据与发布物：
- 项目语料：
build-small-hackathon组织下的公开 Space，作为图谱、搜索、顾问引用和任务覆盖的实时数据。 - 项目快照与向量索引：
data/projects.json、data/project_index.json。 - 任务分类 SFT 数据集：
hackathon-advisor-quest-dataset，用来训练 MiniCPM 任务分类器。 - Codex 会话轨迹：
hackathon-advisor-codex-traces，筛选、精简后用 OpenAI Privacy Filter 脱敏再发布。 - 顾问 LoRA 训练套件：
/api/lora-training-kit.zip，能按真实顾问会话重新生成对话 JSONL、训练配方和适配器卡片。
顾问工作区
顾问工作区保留了原版应用的工作循环：
- Ink：把当前点子和项目索引对比。
- Gap：轮换展示还没被占的空白方向。
- Plan：起草一条能落地的构建路径。
- Compare：重新扫一遍存下的点子板，挑出最强的一页。
- Profile：填上技能、时间、偏好和约束，让计划把“ 一个晚上”“前端原型”“只有 CPU 的 Space”当成真实的范围限制。
每个打过分的页面都带一张确定性的 wood_map：背景点是已索引的 Space，红点是引用到的最相近项目，绿/红点是当前点子。界面和 PNG 导出用的是同一个 Pillow 渲染器。
Codex 在开发中的作用
Codex 是这个项目的工程搭档：把黑客松要求拆成一个个实现切片、检查代码库、搭图谱刷新/存储/缓存这几条路径、加搜索和任务证据界面、跑本地测试和浏览器检查、审查线上 Space 的行为、准备提交和部署更新，还把 README 改写成提交叙述。演示视频也走同样的智能体流程：Codex 帮忙起草带旁白的分镜、操作真实应用、录屏、生成配音、合成视频，再通过读画面帧和 ASR 转写核对成片。这部分媒体流程在应用之外跑，不计入模型预算。完整开发历史在 GitHub 公开。
参赛信息
项目主投 Thousand Token Wood 赛道，同时冲 OpenBMB、OpenAI/Codex、NVIDIA 和 Modal 赞助奖，还有六个附加徽章：
- OpenBMB：MiniCPM5-1B 是工具规划和任务分类的核心语言模型。
- Off the Grid：所有模型都以 开放权重在 Space 自身的 GPU/CPU（或本地机器）上运行，运行时不调第三方推理 API。
- Well-Tuned：两个 MiniCPM5-1B PEFT LoRA 适配器（顾问 + 任务分类器）都发布在 Hub 上，训练套件可复现。
- Off-Brand：自定义
gradio.Server前端，运行路径里没有默认 Gradio 界面。 - Llama Champion：EmbeddingGemma GGUF 向量和所有运行时查询向量都用 llama.cpp 算。
- Sharing is Caring / Field Notes：公开 Codex 会话轨迹；任务分类器微调的构建报告见
docs/quest-classification-lora.md，应用也能导出 Field Notes。 - Tiny Titan：最大的单个模型约 1.08B，远低于 4B 上限。
- Best Agent：每一轮由 MiniCPM5 选一个工具，再由引擎在实时项目数据上走“搜索 → 空白方向 → 评分 → 计划”这条链。
- NVIDIA / Modal：语音输入用 Nemotron ASR；Modal 用来训练任务分类 LoRA，也提供远程索引构建路径（仓库里附带的索引是在本地构建的）。
更多奖项证据见 docs/submission-notes.md。
本地运行
python3.11 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
mkdir -p .cache/advisor-dashboard
ADVISOR_CACHE_DIR=.cache/advisor-dashboard \
ADVISOR_MODEL_BACKEND=minicpm-transformers \
ADVISOR_MODEL_ID=openbmb/MiniCPM5-1B \
ADVISOR_ADAPTER_ID=build-small-hackathon/hackathon-advisor-minicpm5-lora \
ADVISOR_ADAPTER_REVISION=25de69bcde397e1bcdd852923b56a42f10222650 \
ADVISOR_QUEST_ANALYZER_BACKEND=minicpm-transformers \
python app.py
然后打开 http://127.0.0.1:7860。图谱的刷新按钮在本地也走和线上一样的产物替换流程。要刷新项目快照，运行：
python scripts/crawl_hf_spaces.py --org build-small-hackathon --out data/projects.json
python scripts/build_project_index.py --location modal --projects data/projects.json --out data/project_index.json
在 macOS 本地运行时，应用会自动把 llama.cpp 查询向量放进单独的 worker 进程，免得 MiniCPM 的 PyTorch 运行时和 llama.cpp 的 OpenMP 运行时互相干扰。
主要 API
| 接口 | 用途 |
|---|---|
GET /api/dashboard | 图谱点、连线、聚类、任务报告、来源和刷新状态 |
GET /api/dashboard/search?q=... | 对项目、聚类、任务、README 和应用文件文本做 BM25 搜索 |
POST /api/dashboard/chat | 图谱对话（NDJSON 流）：基础模型工具调用、校验结果与地图动作、有依据的回答 |
POST /api/dashboard/refresh | 启动一次后台刷新 |
POST /api/transcribe | 用 NVIDIA NeMo 和 Nemotron ASR 转写语音 |
GET /api/prize-ledger | 模型栈、参数预算、运行状态和奖项证据 |
GET /api/demo-bundle.zip | 演示会话、奖项清单、trace、笔记、章节、LoRA 文件、提交材料包和 PNG |
GET /api/lora-training-kit.zip | SFT 数据、训练配方、适配器卡片和训练命令 |
相关链接
- Hugging Face Space：build-small-hackathon/hackathon-advisor
- GitHub：JacobLinCool/hackathon-advisor
- 演示视频：YouTube
项目作者：JacobLinCool。