# 薪火 · 第二轮迭代 · 技术调研

> 目标：让孩子在网站里**直接点一下就看到 AI 效果**，不用再去 HuggingFace / 通义千问网页注册账号。
>
> 约束：
> - 中等预算（$50/月级别）
> - "点一下就跑"——零注册、零 key 输入
> - 必选能力：文字聊天 + system prompt
> - 高优先级：判官 AI / RAG、图像生成、语音输入、代码沙盒

---

## 一、整体架构选项对比

我们的需求决定了：**AI key 不能放前端**（任何浏览器 F12 都能偷）。所以必须有一层"中间人"。
四种主流路径：

### 选项 A · 浏览器内 WebLLM（无服务器）
**怎么做**：用 WebLLM / transformers.js / @huggingface/transformers，把模型代码 + 权重直接下到孩子的浏览器里跑。

| 维度 | 评价 |
|---|---|
| 启动难度 | ★★ 第一次要下 1-3GB 模型 |
| 运行速度 | M2/M3 Mac：10-20 tok/s；iPad：可玩；Win 老笔记本：很慢 |
| 智能水平 | 当前能本地跑：Qwen2.5-1.5B / Llama 3.2-1B —— 比云上的 Qwen-Plus 弱很多 |
| 隐私 | ★★★★★ 不发任何数据出门 |
| 成本 | $0 |
| 可控 | 完全可控，但只支持有限能力（无图像生成 / 无 RAG 大库） |
| 适合谁 | 萌芽版"玩一下"的轻量场景 |

**结论**：可以作为**降级方案**（用户网络不通 / 没注册时的"应急 AI"），但不能当主路径。

---

### 选项 B · 一个轻量代理 + 单一 AI 提供商
**怎么做**：在 Cloudflare Workers / Vercel Edge Functions 跑一个简单的 proxy，前端 fetch 到 proxy，proxy 加上 hidden API key 转发给上游（通义千问 / DeepSeek / Groq）。

```
浏览器 →（你的网站域名）→ /api/chat → Worker 加 key → 通义千问
                                              ← 流式回 ←
```

| 维度 | 评价 |
|---|---|
| 部署 | Cloudflare Workers 免费 100k 请求/天，Pages 函数也行 |
| 上游成本 | 通义 Qwen-Turbo：约 ¥0.3 / 百万 token（输入），出 ¥0.6。一万孩子用一周大约 $30 |
| 流式输出 | 支持 |
| 上游选 | DeepSeek、通义千问、Groq、OpenRouter（聚合多家）|
| 可控 | 完全可控速率、可加日志、可加 abuse 防御 |
| 适合谁 | 主路径，覆盖萌芽 + 中阶 + 进阶的"文字 AI"需求 |

**结论**：✅ **主路径推荐**。最务实，最简单，成本可控。

---

### 选项 C · OpenRouter 聚合 API（一个 key 调多家）
**怎么做**：注册 OpenRouter（[openrouter.ai](https://openrouter.ai)），一个 key 能调 200+ 模型（Claude、GPT、Gemini、Qwen、Llama、DeepSeek）。Proxy 还是必要的（key 不能给前端）。

| 维度 | 评价 |
|---|---|
| 灵活度 | ★★★★★ 一个 key 通吃，模型可即时切换 |
| 价格 | 略贵于直连（加成约 5-10%）但有免费模型可选（gemini-2.0-flash:free 等） |
| 流式 | 支持 |
| Vision | 支持（很多模型都能看图） |
| 适合谁 | 需要"一会儿用 GPT 一会儿用 Qwen 做对照"的场景，比如审美工作室项目 11 |

**结论**：✅ **强烈推荐**作为主要 AI 后端。代码改一行 `model="..."` 就能换模型，对教学非常合适。

---

### 选项 D · 自建 Ollama 在云上
**怎么做**：租一台 GPU 服务器（Hetzner / Vast.ai 约 $50/月起），跑 Ollama，开一个 OpenAI 兼容的 endpoint。

| 维度 | 评价 |
|---|---|
| 启动 | 需懂运维，ssh + Docker + reverse proxy |
| 成本 | 固定 $50-200/月（无论有人用没人用）|
| 速度 | 视 GPU 而定，可能比云 API 慢 |
| 适合谁 | 长期、稳定流量、想完全自控的场景。**这一轮不推荐** |

---

## 二、最终架构推荐 · 多层 Fallback

```
                     [孩子浏览器]
                          │
                  click "运行 AI"
                          │
                          ▼
              ┌─────────────────────────┐
              │ 我们的 Cloudflare Worker  │
              │  (kindling-ai.dev)       │
              └─────────────────────────┘
                          │
                  speed/cost router
                          │
        ┌─────────────────┼─────────────────┬─────────────┐
        ▼                 ▼                 ▼             ▼
  [Groq 免费层]     [OpenRouter ]     [WebLLM 降级]   [限流屏障]
   超快 + 免费       多模型 + 收费     断网时启用       "今天用太多了"
   (Llama 3.3 70B)  (GPT-4o-mini    (Qwen 1.5B
                    / Claude Haiku    本地)
                    / Qwen-Turbo)
```

**默认路径**：`Groq + Llama 3.3 70B`（免费，超快，质量 ≥ Claude Haiku 一半）
**升级路径**：当孩子要图像生成 / 长文本 / RAG → 自动切到 OpenRouter
**降级路径**：当限流触发或服务宕 → 自动落到 WebLLM 浏览器内

---

## 三、各能力的具体技术选型

### 1. 文字聊天 + system prompt（必选）
- **主**：Groq + Llama 3.3 70B 或 Qwen 2.5 72B（免费层 30 req/min/IP）
- **备**：OpenRouter 调 Qwen-Plus（中文最强，约 ¥0.4/M token）
- **降级**：WebLLM + Qwen 2.5 1.5B
- **流式输出**：是
- **API 形式**：OpenAI 兼容 `/v1/chat/completions`

### 2. 判官 AI / RAG（中阶 + 进阶 项目 11/12）
- **判官**：用 Groq Llama 3.3 70B 跑 LLM-as-judge prompt（够用）
- **RAG embedding**：HuggingFace Inference API 的 `BAAI/bge-small-zh`（中文 embedding，免费）
- **向量库**：浏览器内 IndexedDB + 简单余弦相似度（小数据集 < 1000 条够了）
- **进阶版**：可升到 Pinecone / Qdrant Cloud 免费层

### 3. 图像生成（萌芽版"画一画"、中阶版"配图"）
- **首选**：Cloudflare Workers AI 的 `@cf/black-forest-labs/flux-1-schnell`（FLUX.1 fast，每天免费 50 张）
- **备**：Replicate / Together SDXL-Lightning（约 $0.003/张）
- **看图说话（vision）**：Qwen2.5-VL 或 GPT-4o-mini 通过 OpenRouter

### 4. 语音输入（萌芽版"说话给 AI"）
- **首选**：浏览器原生 `Web Speech API`（免费、零配置，Chrome/Edge 支持中文）
- **降级**：Whisper.cpp WebAssembly（纯前端，能跑但慢）
- **进阶**：Groq Whisper Large v3（每小时只要 $0.04）

### 5. 代码沙盒（中阶 + 进阶 代码俱乐部）
- **HTML/JS**：已有（在 iframe 里跑，零成本）
- **Python**：Pyodide WebAssembly（已部分接入）
- **AI 跑代码**：用 OpenRouter 调任何带 code interpreter 的模型

---

## 四、安全 / 防滥用方案

孩子点一下就能跑 → 也意味着熊孩子可以一秒按 100 次。必须有护栏。

| 措施 | 说明 |
|---|---|
| **每 IP 限流** | Cloudflare 自带：每分钟 30 次，每天 500 次 |
| **响应长度上限** | max_tokens=500（萌芽）/ 1500（中阶）/ 4000（进阶） |
| **禁用敏感模型** | 不开 GPT-4 / Claude Opus 这种贵的 |
| **总开销硬上限** | Worker 每月达 $30 时自动切到只用免费模型 |
| **prompt injection 防御** | 简单关键词过滤（最少限度） |
| **"老师模式" feature flag** | 老师在大屏演示时，可以临时申请高配额 |

---

## 五、上游 AI 供应商对比

| 供应商 | 免费层 | 付费价（per M tok） | 中文质量 | 速度 | 推荐场景 |
|---|---|---|---|---|---|
| **Groq** | 30 req/min × Llama-3.3-70B | $0.59 in / $0.79 out | ⭐⭐⭐ | ⚡⚡⚡⚡⚡ | 默认主路径 |
| **DeepSeek** | 无 | ¥0.5 in / ¥1.5 out | ⭐⭐⭐⭐⭐ | ⚡⚡⚡ | 中文场景升级 |
| **通义千问 (Dashscope)** | 5 元/月送 | ¥0.3-1.2 | ⭐⭐⭐⭐⭐ | ⚡⚡⚡ | 中文备选 |
| **OpenRouter** | 部分 :free 模型 | varies | varies | varies | 多模型聚合 |
| **Cloudflare Workers AI** | 10k neuron/day | 视模型 | ⭐⭐⭐ | ⚡⚡⚡ | 图像生成首选 |
| **HuggingFace Inference** | 限速 | 大量免费模型 | varies | ⚡⚡ | embedding 首选 |
| **Anthropic Claude** | 无 | $0.25-15 | ⭐⭐⭐⭐ | ⚡⚡⚡ | 进阶版"标杆"对照 |

---

## 六、初步成本估算（中等流量场景）

假设：1000 个孩子，每人每天 10 次 AI 调用，每次 500 token。

- **总 token/月**：1000 × 10 × 500 × 30 = 1.5 亿 token / 月
- **如果 100% 走 Groq Llama-3.3-70B**：1.5亿 × $0.59/M = **$88.5/月**
- **如果 50% 走 Groq 免费层 + 50% 走 OpenRouter Qwen-Turbo**：约 **$35/月**
- **加 Cloudflare Workers Paid 一份 ($5/月)**：总共 **$40/月**

✅ **完全在 $50/月预算内**。

---

## 七、为什么不直接用 HuggingFace Spaces 或 Qwen Chat？

> 用户原话："如果让他们去注册别的网站，是有难度的，尤其是像 huggingface 这种太多内容的平台。"

**对**。HuggingFace 对成年开发者很好，但对孩子：
- 注册要邮箱验证 + 同意一长串协议
- UI 是英文 + 偏开发者
- 一旦离开薪火网站去了 HF，孩子就跑掉了 —— 在 HF 主页看到一堆别的 Space，注意力分散
- Assistants 功能找半天找不到入口

我们要把孩子留在薪火域名内，**所有 AI 在我们的 UI 框架里跑**。

---

## 八、推荐的下一步

1. **本周**：把 `kindling-iteration-2/proxy/` 的 Cloudflare Worker 写出来，部署到 `ai.kindling.dev`（或用户自己的域名）
2. **下一周**：把所有"复制 prompt 跳 Qwen"的页面改成"点一下就跑"
3. **再下周**：接图像生成 + 语音输入到萌芽版
4. **再再下周**：接 RAG 到进阶版项目 01 + 11

详细架构在 `ARCHITECTURE.md`，能跑的原型在 `prototype-chat.html` 和 `prototype-judge.html`。