实现细节#

分块逻辑在 scripts/build-vectorize-index.js 的 splitByHeadings() 中：

1
function splitByHeadings(content, articleTitle) {
2
  const lines = content.split("\n");
3
  const chunks = [];
4
  let currentHeadingPath = [];
5
  let currentContent = [];
6

7
  function flush() {
8
    const text = currentContent.join("\n").trim();
9
    if (text.length < 50) return;
10
    chunks.push({ heading: currentHeadingPath.join(" > ") || articleTitle, text });
11
  }
12

13
  for (const line of lines) {
14
    const headingMatch = line.match(/^(#{1,4})\s+(.+)/);
15
    if (headingMatch) {
16
      flush();
17
      currentContent = [];
18
      const level = headingMatch[1].length;
19
      const title = headingMatch[2].trim();
20
      currentHeadingPath = currentHeadingPath.slice(0, level - 1);
21
      currentHeadingPath[level - 1] = title;
22
    } else {
23
      currentContent.push(line);
24
    }
25
  }
26
  flush();
27
  return chunks;
28
}

关键点：

• 只识别 # ~ #### 四级标题，遇到标题就切段
• currentHeadingPath 维护层级路径，如 缓存问题 > 缓存穿透 > 解决方案
• 每个 chunk 的 ID 由 slug::heading 哈希生成，保证同一章节始终对应同一向量 ID
• 每个 chunk 携带 metadata（articleTitle、articlePath、published、category、tags、heading、excerpt），供检索结果展示和去重使用

与 LangChain 递归分块的对比#

LangChain 递归分块的核心逻辑（伪代码）：

1
separators = ["\n\n", "\n", ". ", " ", ""]  # 从大到小
2
for sep in separators:
3
    chunks = text.split(sep)
4
    if all(len(c) <= chunk_size for c in chunks):
5
        break
6
    # 太长的继续用更小的分隔符递归切分

本博客方案的潜在问题：如果一个标题下的内容非常长（比如一个 # 下面有几千字），生成的 chunk 会很大，可能导致 embedding 质量下降、检索粒度太粗。

改进方向：先按 Heading 切分保留语义边界，再对超长段落做二次字符切分，同时让子 chunk 继承父标题路径。

构建脚本#

scripts/build-vectorize-index.js 负责：

1. 读取 src/content/posts/ 下所有非 draft 文章
2. 按 heading 切段，生成 chunk 列表
3. 调用 embedding API 生成向量
4. 批量写入 Cloudflare Vectorize

支持增量更新——通过 .vectorize-manifest.json 记录每篇文章的内容 hash，只处理新增/修改/删除的文章。具体用法和底层 API 见下文「向量索引上传」小节。

Embedding 来源#

两种模式，三者齐备时走第三方 API，否则用 Cloudflare Workers AI 免费模型：

对话模型同样有两种模式：

配置在 .env 中（仅敏感信息），参考 .env.example：

1
# Cloudflare 凭证（必填）
2
CLOUDFLARE_API_TOKEN=xxx
3
CLOUDFLARE_ACCOUNT_ID=xxx
4

5
# 第三方 AI API Key（可选，有则走第三方 API，无则回退 Workers AI）
6
AI_API_KEY=sk-xxx

非敏感配置（API 地址、模型名称、向量维度等）统一在 aiSearchConfig.ts 中管理，无需在 .env 重复配置。

Cloudflare 凭证获取#

CLOUDFLARE_API_TOKEN：

1. 登录 Cloudflare Dashboard
2. 右上角头像 → My Profile → API Tokens → Create Token
3. 选择 Create Custom Token，权限勾选：
   • Account → Vectorize → Edit
   • Account → Workers AI → Use
4. 创建后复制 Token（页面关闭后无法再查看）

CLOUDFLARE_ACCOUNT_ID：

1. 登录 Cloudflare Dashboard
2. 点击任意域名 → 概览页右侧栏 API 区域 → 复制 Account ID
3. 或直接从 URL 中复制：https://dash.cloudflare.com/<account_id>/...

AI_API_KEY（可选）：

当前使用魔搭社区（ModelScope）的免费接口，注册即可获取：

1. 注册 ModelScope
2. 右上角头像 → API-KEY 管理 → 创建 API Key

Worker Secret 配置#

Worker 运行时需要的 AI_API_KEY 不能写在代码中，需在 Cloudflare Dashboard 配置：

1. 登录 Cloudflare Dashboard
2. Workers & Pages → 选择你的 Worker → Settings → Variables and Secrets
3. 添加 Secret 类型变量：AI_API_KEY，值为第三方 API 的 Key

向量索引上传#

构建脚本 scripts/build-vectorize-index.js 通过 Cloudflare REST API 操作 Vectorize（不是 Wrangler CLI）：

1
# 首次使用前，确保 .env 已配置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID
2

3
# 增量更新（只处理新增/修改/删除的文章）
4
node scripts/build-vectorize-index.js
5

6
# 全量重建（删除旧索引，重新创建并上传所有文章向量）
7
node scripts/build-vectorize-index.js --force

全量重建流程：删除旧索引 → 创建新索引（指定维度和 cosine 度量）→ 分批生成 embedding → 分批插入向量。增量更新通过 .vectorize-manifest.json 记录每篇文章的内容 hash，只处理有变化的文章。

底层 API 调用：

1
// 插入向量
2
await fetch(`${API_BASE}/vectorize/v2/indexes/${INDEX_NAME}/insert`, {
3
  method: "POST",
4
  headers: { Authorization: `Bearer ${API_TOKEN}` },
5
  body: JSON.stringify({ vectors }),
6
});
7

8
// 删除向量
9
await fetch(`${API_BASE}/vectorize/v2/indexes/${INDEX_NAME}/delete-by-ids`, {
10
  method: "POST",
11
  headers: { Authorization: `Bearer ${API_TOKEN}` },
12
  body: JSON.stringify({ ids: batch }),
13
});
14

15
// 查询（Worker 运行时通过绑定调用，不需要 API Token）
16
const results = await env.VECTORIZE.query(queryVector, {
17
  topK: 10,
18
  returnMetadata: true,
19
});

1. 统一配置管理#

所有 AI 相关配置集中在 src/config/aiSearchConfig.ts，前端组件、构建脚本、Worker 三方共享：

1
export const aiSearchConfig = {
2
  apiUrl: "https://api-inference.modelscope.cn/v1",  // API 地址
3
  modelName: "deepseek-ai/DeepSeek-V4-Flash",         // LLM 对话模型
4
  embeddingModel: "Qwen/Qwen3-Embedding-8B",          // 向量模型
5
  vectorizeDim: 1024,                                  // 向量维度
6
  batchSize: 500,                                      // 构建脚本批大小
7
  embedBatchSize: 50,                                  // Embedding 请求批大小
8
  indexName: "blog-ai-search",                         // Vectorize 索引名
9
};

Worker 运行时通过 getAiConfig(env) 读取配置，非敏感项从 aiSearchConfig 取值，仅 API Key 从环境变量 env.AI_API_KEY 注入。当配置项和 API Key 都存在时走第三方 API，否则回退到 Cloudflare Workers AI 内置模型。

2. Embedding#

1
async function getEmbedding(env, text) {
2
  const cfg = getAiConfig(env);
3
  if (useThirdParty(env)) {
4
    const res = await fetch(buildApiUrl(cfg.apiUrl, "/v1/embeddings"), {
5
      method: "POST",
6
      headers: {
7
        Authorization: `Bearer ${cfg.apiKey}`,
8
        "Content-Type": "application/json",
9
      },
10
      body: JSON.stringify({
11
        model: cfg.embeddingModel,
12
        input: text,
13
        dimensions: cfg.vectorizeDim,
14
        encoding_format: "float",
15
      }),
16
    });
17
    if (!res.ok)
18
      throw new Error(`Embedding API ${res.status}: ${await res.text()}`);
19
    const data = await res.json();
20
    return data.data?.[0]?.embedding;
21
  }
22
  const result = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text });
23
  return result.data[0];
24
}

模型名和维度均从 aiSearchConfig 读取，切换模型只需改配置文件。

3. 向量检索#

1
const queryVector = await getEmbedding(env, question);
2
const results = await env.VECTORIZE.query(queryVector, {
3
  topK: 10,
4
  returnMetadata: true,
5
});

过滤 score < 0.2 的低相似度结果，按 articlePath 去重后拼接上下文。每条匹配结果格式为 【文章标题 - 章节标题】\n摘要，用 --- 分隔。去重后的文章信息（标题、路径、发布日期、摘要、相似度分数）作为 refs 事件先于回答发送。

4. Prompt 拼接与 system 注入防护#

系统提示（system prompt）决定了 AI 的人格和行为准则。如果用户通过构造请求在 history 中插入 role: "system" 的消息，就可能覆盖或绕过预设人格——这称为 system 注入攻击。

防护措施：在拼接 messages 之前，过滤掉 history 中所有 role === "system" 的条目，确保只有服务端硬编码的 systemPrompt 生效：

1
const safeHistory = history.filter((m) => m.role !== "system").slice(-6);
2

3
const messages = [
4
  { role: "system", content: systemPrompt },
5
  ...safeHistory,
6
  { role: "user", content: question },
7
];

当前人格设定为猫娘「喵墩」，系统提示包含完整的角色背景、语言规范、性格画像等，与博客检索规则拼接后传给 LLM。

5. 流式返回#

SSE 格式，四种事件类型：

1
data: {"type":"refs","articles":[...]}   ← 参考文章（先发）
2
data: {"type":"chunk","text":"..."}       ← 回答文本片段
3
data: {"type":"error","error":"..."}      ← 错误信息
4
data: {"type":"done"}                     ← 结束

LLM 后端由 aiSearchConfig 决定：配置了 apiUrl + modelName + AI_API_KEY 时走第三方 API（OpenAI 兼容格式流），否则回退 Workers AI（@cf/meta/llama-3-8b-instruct，Cloudflare 原生流）。

会话管理#

1
interface SessionMeta {
2
  id: string;      // 会话唯一标识
3
  title: string;   // 自动提取的第一条用户消息（前20字）
4
  updatedAt: number; // 最后更新时间戳
5
}

1
function startNewSession() {
2
  saveCurrentSession();
3
  sessionId = generateSessionId();
4
  messages = [];
5
  showSessionList = false;
6
}

1
{#if showSessionList}
2
  <div class="ai-session-list">
3
    {#each sessionList as sess}
4
      <button
5
        class="ai-session-item"
6
        class:ai-session-item-active={sess.id === sessionId}
7
        onclick={() => switchSession(sess.id)}
8
      >
9
        <div class="ai-session-info">
10
          <span class="ai-session-title">{sess.title}</span>
11
          <span class="ai-session-time">{formatTime(sess.updatedAt)}</span>
12
        </div>
13
        <!-- 悬停显示删除按钮 -->
14
        <span onclick={(e) => { e.stopPropagation(); deleteSession(sess.id); }}>
15
          <Icon icon="material-symbols:close" size="sm" />
16
        </span>
17
      </button>
18
    {/each}
19
  </div>
20
{/if}

1
function switchSession(id: string) {
2
  if (id === sessionId) { showSessionList = false; return; }
3
  saveCurrentSession();
4
  sessionId = id;
5
  messages = loadSessionMessages(id);
6
  showSessionList = false;
7
  scrollToBottom();
8
}

1
function deleteSession(id: string) {
2
  localStorage.removeItem(STORAGE_SESSION_PREFIX + id);
3
  sessionList = sessionList.filter((s) => s.id !== id);
4
  saveSessionListToStorage(sessionList);
5
  if (id === sessionId) {
6
    startNewSession();
7
  }
8
}

1
const MAX_SESSIONS = 20;
2

3
// 保存时检查上限
4
if (sessionList.length > MAX_SESSIONS) {
5
  const removed = sessionList.splice(MAX_SESSIONS);
6
  for (const s of removed) {
7
    localStorage.removeItem(STORAGE_SESSION_PREFIX + s.id);
8
  }
9
}

1
function saveCurrentSession() {
2
  if (!sessionId || messages.length === 0) return;
3
  if (messages.some((m) => m.streaming)) return; // 流式中不保存
4
  localStorage.setItem(STORAGE_SESSION_PREFIX + sessionId, JSON.stringify(messages));
5
  // 更新 sessionList 元数据...
6
}

1
onMount(() => {
2
  sessionList = loadSessionListFromStorage();
3
  if (sessionList.length > 0) {
4
    const latest = sessionList[0];
5
    sessionId = latest.id;
6
    messages = loadSessionMessages(latest.id);
7
  } else {
8
    sessionId = generateSessionId();
9
  }
10
  // ...
11
  return () => {
12
    saveCurrentSession(); // 卸载时保存
13
  };
14
});