AI 聊天功能配置指南

astro-minimax 内置 AI 聊天助手，支持多 Provider 自动故障转移、RAG 检索增强、流式响应和 Mock 降级。本文介绍完整的 AI 配置流程。

概览

AI 聊天系统由以下模块组成：

快速启用

1. 启用 AI 功能

在 src/config.ts 中：

features: {
  ai: true,
},
ai: {
  enabled: true,
  mockMode: false,
  apiEndpoint: "/api/chat",
},

2. 配置 Provider

在 .env 中配置 AI Provider：

# OpenAI 兼容 API（支持 DeepSeek、Moonshot、Qwen 等）
AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=your-api-key
AI_MODEL=gpt-4o-mini

# 站点信息
SITE_AUTHOR=YourName
SITE_URL=https://your-blog.com

3. 构建 AI 数据

astro-minimax ai process       # 生成文章摘要和 SEO 数据
astro-minimax profile build     # 构建作者画像

4. 启动开发服务器

pnpm run dev

AI 聊天按钮会出现在页面右下角。

Provider 配置详解

Cloudflare Workers AI

在 Cloudflare Pages 部署时，可使用免费的 Workers AI：

# wrangler.toml
[ai]
binding = "AI"

Workers AI 作为最高优先级 Provider，不需要 API Key。

OpenAI 兼容 API

支持任何 OpenAI 兼容的 API 服务：

AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=sk-xxx
AI_MODEL=gpt-4o-mini

也可以配置不同模型用于不同任务：

AI_KEYWORD_MODEL=gpt-4o-mini    # 关键词提取模型
AI_EVIDENCE_MODEL=gpt-4o-mini   # 证据分析模型

故障转移机制

flowchart LR
    Request[用户请求] --> W{Workers AI}
    W -->|成功| Response[流式响应]
    W -->|失败 3 次| O{OpenAI API}
    O -->|成功| Response
    O -->|失败| M[Mock 降级]
    M --> Response

    style W fill:#f97316,color:#fff
    style O fill:#3b82f6,color:#fff
    style M fill:#6b7280,color:#fff
    style Response fill:#22c55e,color:#fff

• 连续失败 3 次标记为不健康
• 60 秒后自动尝试恢复
• 所有 Provider 失败时，Mock 保证用户始终收到回复

Mock 模式

开发时不需要真实 API：

ai: {
  enabled: true,
  mockMode: true,  // 开发环境
},

Mock 模式返回预定义的文章推荐和外部资源链接，模拟真实 AI 回复。

AI 安全特性

来源分层协议

AI 回答遵循 L1-L5 来源优先级：

• L1: 博客原始内容（最高优先级）
• L2: 作者简介、项目列表
• L3: 结构化事实数据
• L5: 语言风格（仅影响表达）

隐私保护

自动拒绝回答敏感个人信息：

• 住址、收入、家庭成员、电话、身份信息、年龄

意图分类

7 类意图识别，提升搜索相关性：

• setup、config、content、feature、deployment、troubleshooting、general

质量评估

配置测试集

编辑 datas/eval/gold-set.json 定义测试用例：

{
  "cases": [
    {
      "id": "about-001",
      "category": "about",
      "question": "介绍一下你自己",
      "answerMode": "fact",
      "expectedTopics": ["博客", "AI"],
      "forbiddenClaims": [],
      "lang": "zh"
    }
  ]
}

运行评估

pnpm run ai:eval                             # 本地测试
pnpm run ai:eval -- --url=https://your.com   # 远程测试
pnpm run ai:eval -- --verbose                # 详细输出

通知集成

AI 对话完成后自动发送通知（fire-and-forget）：

# .env
NOTIFY_TELEGRAM_BOT_TOKEN=your-bot-token
NOTIFY_TELEGRAM_CHAT_ID=your-chat-id

通知内容包含：用户问题、AI 回答摘要、引用文章、Token 用量、各阶段耗时。

详见 通知系统配置指南。

环境变量参考

下一步

• 功能特性总览 — 了解所有 AI 功能
• CLI 工具指南 — AI 处理命令详解
• 通知系统 — 配置 AI 对话通知
• 部署指南 — Cloudflare Workers AI 部署