快速開始
Quick Start

本指南說明如何將 SEO 知識洞察 API 整合至前端應用程式。

This guide covers integrating the SEO Knowledge Insight API into a frontend application.

基本設定
Base Configuration

const API_BASE = process.env.NEXT_PUBLIC_SEO_API_URL || "http://localhost:8002";
const API_KEY = process.env.SEO_API_KEY; // server-side only, never expose to browser

async function seoApi(path: string, options?: RequestInit) {
  const res = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY!,
      ...options?.headers,
    },
  });
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}

警告：API Key 必須保留在伺服器端。使用代理路由（例如 Next.js API route）轉發請求，絕不要在瀏覽器端嵌入金鑰。
Warning: API Key must stay server-side. Use a proxy route (e.g. Next.js API route) to forward requests — never embed the key in browser code.

常用操作
Common Operations

搜尋知識庫
Search the Knowledge Base

const results = await seoApi("/api/v1/search", {
  method: "POST",
  body: JSON.stringify({ query: "Core Web Vitals optimization", top_k: 5 }),
});

// results.results[] contains { question, answer, score, source, category }

RAG 對話（單輪）
RAG Chat (Single Turn)

const chat = await seoApi("/api/v1/chat", {
  method: "POST",
  body: JSON.stringify({
    message: "How to improve LCP?",
    mode: "rag", // "rag" or "agent"
  }),
});

// chat.answer -- AI-generated answer with citations
// chat.sources[] -- relevant Q&A sources
// chat.mode -- actual mode used ("rag" | "agent" | "context-only")
// chat.metadata -- model, tokens, duration

多輪對話（Session）
Multi-Turn Chat with Sessions

// 1. Create session
const session = await seoApi("/api/v1/sessions", { method: "POST" });
const sessionId = session.id;

// 2. Send messages (context preserved)
const msg1 = await seoApi(`/api/v1/sessions/${sessionId}/messages`, {
  method: "POST",
  body: JSON.stringify({ message: "What is canonical URL?" }),
});

// 3. Follow up (session remembers previous messages)
const msg2 = await seoApi(`/api/v1/sessions/${sessionId}/messages`, {
  method: "POST",
  body: JSON.stringify({ message: "How does it affect SEO?" }),
});

// 4. Get full history
const history = await seoApi(`/api/v1/sessions/${sessionId}`);

瀏覽 QA 知識庫
Browse QA Knowledge Base

// List with filters
const qa = await seoApi(
  "/api/v1/qa?category=Technical%20SEO&difficulty=advanced&limit=20"
);

// Get single QA detail
const detail = await seoApi("/api/v1/qa/a1b2c3d4e5f67890");

// Get all categories
const categories = await seoApi("/api/v1/qa/categories");

對話模式參數
Chat Mode Parameter

mode 參數控制 API 處理請求的方式：

The mode parameter controls how the API processes your request:

// Force RAG mode (faster)
await seoApi("/api/v1/chat", {
  method: "POST",
  body: JSON.stringify({ message: "What is robots.txt?", mode: "rag" }),
});

// Force agent mode (more thorough)
await seoApi("/api/v1/chat", {
  method: "POST",
  body: JSON.stringify({ message: "Compare canonical vs 301 redirect for SEO", mode: "agent" }),
});