AI 功能详解

ShokaX 通过 HyC 提供了三项 AI 功能：文本嵌入向量（用于相似文章推荐）、AI 文章摘要 和 余弦相似度推荐。所有 AI 计算都在本地或通过 API 调用完成。

架构概述

hyc sync
  ├── embedding.enabled=true?
  │     ├── 文章 Markdown → 文本分块（按句子边界）
  │     ├── Hugging Face Transformers → 向量化每个 chunk
  │     ├── 均值池化 + L2 归一化 → 最终文章向量
  │     └── 存入数据库
  │
  └── summary.enabled=true?
        ├── 文章 Markdown → 去除 frontmatter → 截断
        ├── 调用 OpenAI 兼容 API → 生成摘要
        └── 存入数据库

前端展示：

博客文章页
  ├── aiSummary.enable=true? → AiSummaryCard 组件
  └── aiRecommend.enable=true?
        ├── POST /posts/similar → 余弦相似度
        └── AiSimilarPosts 组件

1. 文本嵌入向量

技术原理

使用 Hugging Face Transformers.js 在本地生成嵌入向量：

1. 文本预处理：去除 frontmatter、Markdown 语法、代码块
2. 智能分块：按句子边界分割，每 chunk ≤ maxChunkChars 字符
3. 向量化：feature-extraction 模型将每 chunk 转为高维向量
4. 均值池化 + L2 归一化：得到最终文章向量

配置（hyacine.yml）

embedding:
  enabled: true
  model: onnx-community/Qwen3-Embedding-0.6B-ONNX
  maxChunkChars: 512

推荐模型

模型	维度	语言
onnx-community/Qwen3-Embedding-0.6B-ONNX	1024	多语言 ⭐默认
Xenova/paraphrase-multilingual-MiniLM-L12-v2	384	多语言（轻量替代）
Xenova/all-MiniLM-L6-v2	384	英文

2. AI 文章摘要

技术原理

调用 OpenAI 兼容 API，系统提示词引导生成 80-180 字中文精炼概括。

配置（hyacine.yml）

summary:
  enabled: true
  apiBaseUrl: https://openrouter.ai/api/v1
  apiKey: sk-your-api-key
  model: openai/gpt-4o-mini
  maxInputChars: 8000
  maxOutputTokens: 256
  temperature: 0.2

支持的 API：OpenAI、DeepSeek、通义千问、Ollama 等任何兼容接口。

增量更新

通过 rapidhash 检测内容变化，仅在文章内容或模型变更时重新生成。

3. 相似文章推荐

技术原理

使用 中心化余弦相似度 算法：所有向量减去均值消除全局偏差 → L2 归一化 → 计算余弦相似度 → 排序返回 top-N。

主题配置

src/theme.config.ts

export default defineConfig({
  hyc: {
    enable: true,
    aiSummary: {
      enable: true,
      title: "AI 摘要",
      showModel: true,
    },
    aiRecommend: {
      enable: true,
      limit: 3,
      minSimilarity: 0.4,
    },
  },
});

前端配置项

字段	类型	默认值	说明
hyc.enable	boolean	false	HyC 总开关
hyc.aiSummary.enable	boolean	true	显示 AI 摘要卡片
hyc.aiSummary.title	string	"AI 摘要"	卡片标题
hyc.aiSummary.showModel	boolean	true	显示模型名
hyc.aiRecommend.enable	boolean	true	显示推荐文章
hyc.aiRecommend.limit	number	3	最多推荐数（max 50）
hyc.aiRecommend.minSimilarity	number	0.4	最低相似度（0~1）

完整工作流

① 配置 hyacine.yml

embedding:
  enabled: true
  model: Xenova/paraphrase-multilingual-MiniLM-L12-v2
  maxChunkChars: 512

summary:
  enabled: true
  apiBaseUrl: https://api.deepseek.com/v1
  apiKey: sk-your-key
  model: deepseek-chat
  maxInputChars: 2000
  maxOutputTokens: 256
  temperature: 0.7

② 运行同步

hyc sync

③ 配置主题

src/theme.config.ts

export default defineConfig({
  hyc: {
    enable: true,
    aiSummary: { enable: true, title: "AI 摘要", showModel: true },
    aiRecommend: { enable: true, limit: 3, minSimilarity: 0.4 },
  },
});

④ 构建博客

bun run build

常见问题

Q: 嵌入生成很慢？

首次需下载模型（几百 MB）。后续只处理变更文章。不需要时设 embedding.enabled: false。

Q: 摘要不显示？

确认 hyc sync 摘要生成成功、API 配置正确、hyc.enable 和 aiSummary.enable 为 true。

Q: 推荐不够相关？

换更高维度模型、降低 minSimilarity、确保文章内容足够丰富。

Q: API 密钥安全？

apiKey 存储在 hyacine.yml 中，建议加入 .gitignore。