feat: 实现RAG Grounding服务功能

基于promptx/outfit-match中的query_llm_with_grounding实现，遵循Tauri开发规范 ## 新增功能 - 实现RAG Grounding核心服务逻辑 - 支持基于Vertex AI Search的检索增强生成 - 集成Cloudflare Gateway和Google Gemini API - 提供完整的TypeScript类型定义和前端服务封装 ## 技术架构 - Rust后端：GeminiService扩展RAG功能 - Tauri命令：query_rag_grounding, test_rag_grounding_connection, get_rag_grounding_config - 前端服务：RagGroundingService类，支持统计监控和错误处理 - 数据模型：完整的请求/响应结构和配置管理 ## 核心特性 - 检索增强生成：基于数据存储的智能检索和内容生成 - 容错机制：内置重试机制和错误处理 - 性能监控：响应时间统计和性能指标 - 类型安全：完整的TypeScript类型定义 - 会话管理：支持上下文保持的对话功能 ## 测试覆盖 - 25个单元测试，覆盖核心功能和边界情况 - 包括序列化/反序列化、错误处理、配置验证等 - 所有测试通过，确保功能正确性 ## 文档和示例 - 完整的API文档 (docs/rag-grounding-api.md) - 详细的使用示例 (examples/rag-grounding-usage.ts) - 包含最佳实践和错误处理指南 ## 遵循规范 - 严格遵循promptx/tauri-desktop-app-expert开发规范 - 安全第一：最小权限原则，数据加密保护 - 性能优先：异步处理，响应时间优化 - 模块化设计：清晰的架构分层 - 错误处理完善：全面的错误处理和用户反馈
2025-07-21 21:07:03 +08:00
parent c3c72ce8bd
commit 1fb5468ecc
10 changed files with 1838 additions and 1 deletions
--- a/docs/rag-grounding-api.md
+++ b/docs/rag-grounding-api.md
@@ -0,0 +1,264 @@
+# RAG Grounding API 文档
+
+## 概述
+
+RAG Grounding 服务基于 Google Vertex AI Search 和 Gemini 模型，提供检索增强生成（Retrieval-Augmented Generation）功能。该服务参考了 `promptx/outfit-match` 项目中的 `query_llm_with_grounding` 实现，遵循 Tauri 桌面应用开发规范。
+
+## 核心特性
+
+- **检索增强生成**：基于数据存储的智能检索和内容生成
+- **Cloudflare Gateway 集成**：通过 Cloudflare Gateway 访问 Google Vertex AI
+- **容错机制**：内置重试机制和错误处理
+- **类型安全**：完整的 TypeScript 类型定义
+- **性能监控**：响应时间统计和性能指标
+
+## API 接口
+
+### 1. 查询 RAG Grounding
+
+**命令**: `query_rag_grounding`
+
+**请求参数**:
+```typescript
+interface RagGroundingRequest {
+  user_input: string;           // 用户查询内容
+  config?: RagGroundingConfig;  // 可选配置
+  session_id?: string;          // 会话ID
+}
+```
+
+**响应数据**:
+```typescript
+interface RagGroundingResponse {
+  answer: string;                        // AI 生成的回答
+  grounding_metadata?: GroundingMetadata; // Grounding 元数据
+  response_time_ms: number;              // 响应时间（毫秒）
+  model_used: string;                    // 使用的模型
+}
+```
+
+**使用示例**:
+```typescript
+import { queryRagGrounding } from '../services/ragGroundingService';
+
+const result = await queryRagGrounding("如何搭配牛仔裤？", {
+  sessionId: "user-session-123",
+  customConfig: {
+    temperature: 0.7,
+    max_output_tokens: 4096
+  }
+});
+
+if (result.success) {
+  console.log("回答:", result.data?.answer);
+  console.log("来源:", result.data?.grounding_metadata?.sources);
+} else {
+  console.error("查询失败:", result.error);
+}
+```
+
+### 2. 测试连接
+
+**命令**: `test_rag_grounding_connection`
+
+**响应数据**: `string` - 连接测试结果
+
+**使用示例**:
+```typescript
+import { testRagGroundingConnection } from '../services/ragGroundingService';
+
+const status = await testRagGroundingConnection();
+console.log("服务状态:", status.available ? "可用" : "不可用");
+console.log("测试结果:", status.connectionTest);
+```
+
+### 3. 获取配置信息
+
+**命令**: `get_rag_grounding_config`
+
+**响应数据**:
+```typescript
+interface RagGroundingConfigInfo {
+  base_url: string;
+  model_name: string;
+  timeout: number;
+  max_retries: number;
+  retry_delay: number;
+  temperature: number;
+  max_tokens: number;
+  cloudflare_project_id: string;
+  cloudflare_gateway_id: string;
+  google_project_id: string;
+  regions: string[];
+}
+```
+
+## 配置选项
+
+### RagGroundingConfig
+
+```typescript
+interface RagGroundingConfig {
+  project_id: string;          // Google Cloud 项目ID
+  location: string;            // 数据存储位置
+  data_store_id: string;       // 数据存储ID
+  model_id: string;            // 模型ID
+  temperature: number;         // 生成温度 (0.0-2.0)
+  max_output_tokens: number;   // 最大输出令牌数
+  system_prompt?: string;      // 系统提示词
+}
+```
+
+### 默认配置
+
+```typescript
+const DEFAULT_CONFIG = {
+  project_id: "gen-lang-client-0413414134",
+  location: "global",
+  data_store_id: "default_data_store",
+  model_id: "gemini-2.5-flash",
+  temperature: 1.0,
+  max_output_tokens: 8192,
+};
+```
+
+## Grounding 元数据
+
+### GroundingMetadata
+
+```typescript
+interface GroundingMetadata {
+  sources: GroundingSource[];    // 检索来源
+  search_queries: string[];      // 搜索查询
+}
+```
+
+### GroundingSource
+
+```typescript
+interface GroundingSource {
+  title: string;              // 来源标题
+  uri?: string;               // 来源URI
+  snippet: string;            // 内容片段
+  relevance_score?: number;   // 相关性评分 (0.0-1.0)
+}
+```
+
+## 错误处理
+
+### 错误类型
+
+```typescript
+enum RagGroundingErrorType {
+  NETWORK_ERROR = 'NETWORK_ERROR',           // 网络错误
+  AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR', // 认证错误
+  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',   // 配置错误
+  TIMEOUT_ERROR = 'TIMEOUT_ERROR',           // 超时错误
+  PARSING_ERROR = 'PARSING_ERROR',           // 解析错误
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',           // 未知错误
+}
+```
+
+### 错误处理示例
+
+```typescript
+try {
+  const result = await queryRagGrounding("测试查询");
+  if (!result.success) {
+    switch (result.error) {
+      case 'NETWORK_ERROR':
+        console.error("网络连接失败，请检查网络设置");
+        break;
+      case 'AUTHENTICATION_ERROR':
+        console.error("认证失败，请检查API密钥");
+        break;
+      default:
+        console.error("查询失败:", result.error);
+    }
+  }
+} catch (error) {
+  console.error("系统错误:", error);
+}
+```
+
+## 性能监控
+
+### 统计信息
+
+```typescript
+interface RagGroundingStats {
+  totalQueries: number;         // 总查询次数
+  successfulQueries: number;    // 成功查询次数
+  failedQueries: number;        // 失败查询次数
+  averageResponseTime: number;  // 平均响应时间
+  fastestResponseTime: number;  // 最快响应时间
+  slowestResponseTime: number;  // 最慢响应时间
+  lastQueryTime?: Date;         // 最后查询时间
+}
+```
+
+### 获取统计信息
+
+```typescript
+import { getRagGroundingStats } from '../services/ragGroundingService';
+
+const stats = getRagGroundingStats();
+console.log(`成功率: ${(stats.successfulQueries / stats.totalQueries * 100).toFixed(2)}%`);
+console.log(`平均响应时间: ${stats.averageResponseTime.toFixed(0)}ms`);
+```
+
+## 最佳实践
+
+### 1. 查询优化
+
+- 使用清晰、具体的查询语句
+- 适当设置温度参数（创意性 vs 准确性）
+- 合理设置最大输出令牌数
+
+### 2. 会话管理
+
+- 为相关查询使用相同的 session_id
+- 定期清理过期会话
+
+### 3. 错误处理
+
+- 实现重试机制
+- 提供用户友好的错误信息
+- 记录详细的错误日志
+
+### 4. 性能优化
+
+- 监控响应时间
+- 缓存常见查询结果
+- 使用适当的超时设置
+
+## 开发规范
+
+本 RAG Grounding 服务严格遵循 `promptx/tauri-desktop-app-expert` 中定义的开发规范：
+
+- **安全第一**：最小权限原则，数据加密保护
+- **性能优先**：异步处理，响应时间优化
+- **类型安全**：完整的 TypeScript 类型定义
+- **模块化设计**：清晰的架构分层
+- **错误处理完善**：全面的错误处理和用户反馈
+
+## 技术架构
+
+```
+Frontend (TypeScript)
+    ↓
+Tauri Commands
+    ↓
+Rust Backend (GeminiService)
+    ↓
+Cloudflare Gateway
+    ↓
+Google Vertex AI Search + Gemini
+```
+
+## 依赖项
+
+- **Rust**: anyhow, serde, tokio, reqwest
+- **TypeScript**: @tauri-apps/api
+- **Google Cloud**: Vertex AI Search, Gemini API
+- **Cloudflare**: Gateway 服务