React 个体作品集集成双模 AI 聊天机器人，Agentic RAG 混合检索与全链路追踪

方案简介

本方案来自 santifer.io —— 一个「生产级交互式作品集」，核心是用一个以第一人称回答问题的 AI 聊天机器人「Santi」来证明简历所描述的技能。README 明确指出静态 PDF 只罗列技能而无法证明技能，该项目则让作品集本身成为技能演示。

技术配方为：前端 React + TypeScript + Vite + Tailwind，聊天入口为 React 挂件 FloatingChat.tsx，请求发往部署在 Vercel Edge 上的 api/chat.js；后端用 Claude Sonnet 做 tool_use 决策与流式生成，需要检索时走 Agentic RAG 流水线：OpenAI text-embedding-3-small 生成向量，Supabase pgvector（语义检索）+ 全文检索（BM25）做混合搜索，再用 Claude Haiku 做重排与多样化；每一跳都通过 Langfuse 追踪（含成本）；打分通过 waitUntil 异步执行，零额外延迟。

适合希望构建可观测、可评估、带安全防线的个人/小型 LLM 应用的开发者。

亮点与能力

• AI Chatbot "Santi"：Text (Claude Sonnet) + Voice (OpenAI Realtime API)，以第一人称作为 Santiago 回答
• Agentic RAG：混合检索（pgvector + BM25）+ Haiku 重排，仅在需要时激活（tool_use 决策）
• 6-Layer Defense：关键词检测、金丝雀令牌、指纹、反提取、在线安全评分、对抗红队，越狱实时邮件告警
• 71 Automated Evals：10 类测试，每次 push 作为 CI 门禁
• LLMOps Dashboard：私有 /ops，8 个标签页展示 Langfuse + Supabase 真实生产数据
• Closed Loop：Trace → 在线评分 → 质量 < 0.7 → 自动生成测试 → CI 阻断部署
• 流式输出：React 挂件通过流式 SSE 呈现回复，附带快速提示词与联系 CTA
• 异步评分零延迟：waitUntil → Haiku scoring (0ms added latency)

组成与分工

• React / FloatingChat.tsx：聊天挂件，负责流式 SSE、快速提示词、联系 CTA
• Vercel Edge / api/chat.js：主聊天边缘函数，承载 RAG、追踪、评分、流式与防御
• Claude Sonnet：tool_use 决策（是否触发 RAG）+ 流式生成最终回答
• OpenAI embeddings (text-embedding-3-small)：文本向量化，供语义检索
• Supabase pgvector + 全文检索：语义（pgvector）与 BM25 混合搜索的知识库
• Claude Haiku：RAG 结果重排与多样化；另用于异步在线评分与 LLM-as-Judge 评测
• Langfuse：每个 span 的全链路追踪与成本记录，同时作为 prompt registry（含文件 fallback）
• api/_shared/rag.js：RAG 流水线——混合搜索、重排、成本追踪、意图分类

前置要求

• 前端：React + TypeScript + Vite + Tailwind
• 后端运行时：Vercel（Edge Functions）
• 模型 API：Claude（Sonnet / Haiku）、OpenAI（embeddings）
• 数据库：Supabase（启用 pgvector 扩展，含全文检索）
• 可观测性：Langfuse 账号与追踪密钥

实施步骤

1. 搭建前端与聊天挂件

用 React + TypeScript + Vite + Tailwind 建站，集成 src/FloatingChat.tsx 聊天挂件。

2. 部署边缘聊天 API

将 api/chat.js 部署到 Vercel Edge，作为主聊天入口，内部串联系统提示词、Claude 决策、RAG、流式生成、Langfuse 追踪与安全防御。

3. 准备知识库与混合检索

在 Supabase 中启用 pgvector，将文档用 OpenAI text-embedding-3-small 向量写入；检索时同时使用 pgvector 语义搜索与全文 BM25，再由 Claude Haiku 重排。

4. 接入 Langfuse

配置追踪，使每个 span（含成本）都上报；系统提示词走 Langfuse prompt registry，chatbot-prompt.txt 仅作 fallback（生产使用 Langfuse v5）。

5. 运行评测与红队

通过 npm 脚本运行 71 条自动评测与红队对抗测试：

npm run evals

npm run adversarial

6. 搭建 /ops 运维面板

部署 api/ops/ 下的 auth/stats/traces/evals 等端点，以 OPS_DASHBOARD_SECRET 鉴权，展示 Langfuse 与 Supabase 真实数据。

使用与配置要点

日常运行

• 聊天挂件以流式 SSE 输出回答，RAG 引用带 source badges（来源徽标）
• 评分经 waitUntil 异步执行，用户侧零额外延迟
• 提示词更新在 Langfuse registry 中进行版本管理

验证与监控

• 访问私有 /ops 面板查看 8 个标签页：Overview / Conversations / Costs / RAG / Security / Evals / Voice / System
• Costs 页按 toolDecision/embedding/reranking/generation/voice 拆分成本（数据源 trace.metadata.cost）
• Security 页展示防御漏斗、安全评分分布与越狱列表
• 闭环机制：质量 < 0.7 的 trace 会自动生成测试，CI 门禁阻断部署

注意事项与常见问题

• chatbot-prompt.txt 只是 fallback 提示词，生产环境使用 Langfuse v5 的注册提示词
• /ops 面板是私有、密码保护的（校验 OPS_DASHBOARD_SECRET）
• RAG 仅按需激活（由 Claude tool_use 决策），并非每条消息都检索
• 评测约 70% 为确定性断言（contains/regex/词数），约 30% 为 LLM-as-Judge（Haiku），需注意 judge 的成本与偏差

优缺点

• ✓ 混合检索+重排提升 RAG 质量
• ✓ 每步追踪成本可观测
• ✕ 组件多，部署链路复杂
• ✕ 依赖多个付费 API

出处

本方案挖掘自开源项目 santifer/cv-santiago，方案内容与实施命令均来自其 README 原文。