跳到主要内容

RAG 知识库与 AI 浮窗方案

· 阅读需 2 分钟
CCLEE
CCLEE

在为企业客户构建智能咨询系统时设计的 RAG 浮窗方案，以下是完整实现。

架构​

用户 → Docusaurus → 浮窗组件 → RAG API → 向量数据库
                            ↑
                        sync-to-rag.js
                            ↑
                        docs/*.md

RAG 同步​

配置​

变量默认值
RAG_URLhttp://localhost:3003
RAG_COLLECTIONproduct_help
RAG_API_KEY''

分块规则​

固定 750 字/块 (约 500 token)
重叠 75 字 (约 50 token)
按字数切分，不考虑标题边界

同步命令​

npm run sync-rag:dry  # 预览
npm run sync-rag      # 执行

Frontmatter​

rag: true          # 同步 | false 删除
rag_tags:          # 可选
  - 标签1
  - 标签2

API​

// DELETE
DELETE /documents?collection={collection}&doc_id={docId}

// POST /index
{
  collection: string,
  documents: Array<{
    doc_id: string,      // {docId}_chunk_{index}
    doc_name: string,
    chunk_id: string,
    chunk_text: string,
    metadata: {
      title: string,
      tags: string[],
      url: string,
      section_title: string
    }
  }>
}

AI 浮窗​

核心​

文件职责
src/components/FloatingChat.jsx组件
src/rag-api-config.js配置
src/theme/Layout/index.js挂载

状态​

isOpen, messages, input, isLoading, showBadge

场景​

getPageType(pathname) → 'browser-plugin' | 'ai-analytics' | 'default'

WELCOME_MESSAGES[pageType]
QUICK_QUESTIONS[pageType]

API 调用​

POST RAG_API_URL
{
  collection: 'product_help',
  question: string
}
→ {
  answer: string,
  sources: [{source, title}],
  cached: boolean,
  similarity: number
}

响应式​

条件宽度高度
<640pxcalc(100vw - 32px)60vh
≥640px380px520px

暗色​

useColorMode() → isDark
// #1F2937 / #374151 / #111827

工作流​

开发​

vim docs/guide.md
git add docs/ && git commit && git push
# 管理后台一键同步（替代 SSH 手动同步）

部署​

git pull
npm run build
# Nginx 静态托管，立即生效

数据结构​

文档块​

{
  doc_id: string,
  doc_name: string,
  chunk_id: string,
  chunk_text: string,
  metadata: { title, tags[], url, section_title }
}

RAG 请求/响应​

// Request
{ collection: string, question: string }

// Response
{
  answer: string,
  sources: [{ source: string, title: string }],
  collection: string,
  cached: boolean,
  similarity: number
}

故障排查​

症状检查
同步失败curl http://localhost:3003/health
echo $RAG_URL
frontmatter rag: true
浮窗无响应浏览器 CSP 错误
RAG_API_URL 注入
curl https://rag.aigent.ren/query
回答不准文档已同步
标题结构清晰
rag_tags 包含关键词

相关​