AI Chat Configuration Guide

astro-minimax includes a built-in AI chat assistant with multi-provider failover, RAG retrieval, streaming responses, and Mock fallback. This guide covers the complete setup.

Quick Setup

1. Enable AI

In src/config.ts:

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

2. Configure Provider

In .env:

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. Build AI Data

astro-minimax ai process       # Generate summaries + SEO data
astro-minimax profile build     # Build author profile

4. Start Dev Server

pnpm run dev

Provider Configuration

Cloudflare Workers AI

Free AI with Cloudflare Pages deployment:

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

OpenAI Compatible API

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

Failover Chain

flowchart LR
    Request[User Request] --> W{Workers AI}
    W -->|Success| Response[Streaming Response]
    W -->|3 failures| O{OpenAI API}
    O -->|Success| Response
    O -->|Fail| M[Mock Fallback]
    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

Security Features

• Source Priority Protocol: L1-L5 source layers prevent hallucination
• Privacy Protection: Auto-refuses sensitive personal info queries
• Intent Classification: 7 intent categories for better search relevance

Quality Evaluation

pnpm run ai:eval                             # Test local
pnpm run ai:eval -- --url=https://your.com   # Test production

Edit datas/eval/gold-set.json to customize test cases.

Environment Variables

Related

• Feature Overview — All AI features
• CLI Guide — AI processing commands
• Notification System — AI chat notifications
• Deployment Guide — Cloudflare Workers AI deployment