Skip to main content

RAG Knowledge Base and AI Floating Widget Solution

Β· 2 min read

Designed this RAG floating widget solution while building an intelligent consultation system for enterprise clients. Here's the complete implementation.

Architecture​

User β†’ Docusaurus β†’ Floating Widget β†’ RAG API β†’ Vector Database
                              ↑
                          sync-to-rag.js
                              ↑
                          docs/*.md

RAG Sync​

Configuration​

VariableDefault
RAG_URLhttp://localhost:3003
RAG_COLLECTIONproduct_help
RAG_API_KEY''

Chunking Rules​

Fixed 750 characters/chunk (~500 tokens)
Overlap 75 characters (~50 tokens)
Split by character count, ignoring heading boundaries

Sync Commands​

npm run sync-rag:dry  # Preview
npm run sync-rag      # Execute

Frontmatter​

rag: true          # Sync | false to delete
rag_tags:          # Optional
  - tag1
  - tag2

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 Floating Widget​

Core Files​

FileResponsibility
src/components/FloatingChat.jsxComponent
src/rag-api-config.jsConfiguration
src/theme/Layout/index.jsMounting

State​

isOpen, messages, input, isLoading, showBadge

Scenarios​

getPageType(pathname) β†’ 'browser-plugin' | 'ai-analytics' | 'default'

WELCOME_MESSAGES[pageType]
QUICK_QUESTIONS[pageType]

API Call​

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

Responsive Design​

ConditionWidthHeight
<640pxcalc(100vw - 32px)60vh
β‰₯640px380px520px

Dark Mode​

useColorMode() β†’ isDark
// #1F2937 / #374151 / #111827

Workflow​

Development​

vim docs/guide.md
git add docs/ && git commit && git push
# One-click sync from admin panel (replaces manual SSH sync)

Deployment​

git pull
npm run build
# Nginx static hosting, takes effect immediately

Data Structures​

Document Chunk​

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

RAG Request/Response​

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

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

Troubleshooting​

SymptomCheck
Sync failedcurl http://localhost:3003/health
echo $RAG_URL
frontmatter rag: true
Widget unresponsiveBrowser CSP errors
RAG_API_URL injection
curl https://rag.ccleeai.com/query
Inaccurate answersDocuments synced
Clear heading structure
rag_tags contains keywords