feat(spx-backend): implement independent search/recommend thresholds and project context performance optimization

Author: freshspf

AI_IMAGE_GENERATION_API.md

@@ -179,18 +179,24 @@ XBuilder 的 AI 图像生成系统支持多种生成提供商（SVG.IO、Recraft
 3. 执行语义搜索（仅搜索，不生成）
 4. 返回增强后的搜索结果
 
-### 5. 项目上下文生成
+### 5. 项目上下文生成/更新
 
 **接口路径**: `POST /projects/context/generate`
 
-**描述**: 为项目生成或更新智能上下文关键词，用于后续的图像推荐增强。
+**描述**: 创建或更新项目的智能上下文关键词。该接口会检查是否已存在项目上下文，如果存在则直接返回缓存结果，除非明确要求重新生成。
+
+**使用场景**:
+- **项目初始化**: 为新项目生成关键词
+- **项目信息更新**: 项目名称或描述变更时更新关键词
+- **强制刷新**: 需要重新生成更准确关键词时
 
 **请求参数**:
 ```json
 {
   "project_id": 123,                     // 必需，项目ID，必须为正整数
   "project_name": "太空冒险游戏",          // 必需，项目名称，1-255字符
-  "project_description": "一个关于太空探索和外星文明的冒险游戏" // 可选，项目描述
+  "project_description": "一个关于太空探索和外星文明的冒险游戏", // 可选，项目描述
+  "force_regenerate": false              // 可选，强制重新生成，默认false
 }
 ```
 
@@ -222,11 +228,13 @@ XBuilder 的 AI 图像生成系统支持多种生成提供商（SVG.IO、Recraft
 ```
 
 **功能特性**:
+- **智能缓存**: 自动检查现有上下文，避免重复LLM调用
 - **AI智能分析**: 使用大语言模型分析项目内容
 - **关键词生成**: 自动生成15-20个相关关键词
 - **多语言支持**: 支持中英文关键词混合
 - **智能去重**: 自动去除重复和无效关键词
 - **优先级排序**: 按重要性对关键词排序
+- **性能优化**: 缓存机制大幅减少响应时间和API成本
 
 **关键词生成策略**:
 1. **主题相关**: 涵盖项目主题相关的物体、场景
@@ -235,7 +243,48 @@ XBuilder 的 AI 图像生成系统支持多种生成提供商（SVG.IO、Recraft
 4. **技术规范**: 每个关键词简短精确（1-50字符）
 5. **数量控制**: 最多20个关键词，避免过载
 
-### 6. 提交反馈
+### 6. 项目上下文查询
+
+**接口路径**: `GET /projects/context?project_id=123`
+
+**描述**: 快速获取现有的项目上下文关键词，用于前端搜索时的性能优化。该接口只查询数据库，不调用LLM。
+
+**使用场景**:
+- **前端搜索**: 在用户进行图像搜索时快速获取项目上下文
+- **上下文检查**: 检查项目是否已有生成的上下文
+- **性能优化**: 避免不必要的LLM调用
+
+**请求参数**:
+- `project_id`: 项目ID（URL参数，必需）
+
+**响应示例**:
+```json
+{
+  "project_id": 123,
+  "name": "太空冒险游戏",
+  "description": "一个关于太空探索和外星文明的冒险游戏",
+  "related_words": [
+    "宇宙飞船",
+    "外星人",
+    "星球",
+    "太空站",
+    "科幻",
+    "冒险"
+  ],
+  "created_at": "2025-01-15T10:30:00Z"
+}
+```
+
+**错误处理**:
+- 如果项目上下文不存在，返回404错误
+- 建议前端在接收到404后调用生成接口创建上下文
+
+**性能特点**:
+- **毫秒级响应**: 直接数据库查询，无LLM调用
+- **高并发支持**: 支持大量并发查询请求
+- **缓存友好**: 可配合前端缓存进一步优化
+
+### 7. 提交反馈
 
 **接口路径**: `POST /images/feedback`
 
@@ -533,6 +582,7 @@ type ProjectContextParams struct {
     ProjectID          int64  `json:"project_id"`           // 项目ID
     ProjectName        string `json:"project_name"`         // 项目名称
     ProjectDescription string `json:"project_description"`  // 项目描述
+    ForceRegenerate    bool   `json:"force_regenerate"`     // 强制重新生成
 }
 ```
 
@@ -554,13 +604,36 @@ type RecommendedImageResult struct {
 - **语义搜索**: `POST /v1/resource/search`
 - **健康检查**: `GET /health`
 
-### 搜索策略
+### 搜索策略与阈值配置
+
+系统支持为不同使用场景配置独立的相似度阈值：
+
+#### 阈值类型
+- **搜索阈值** (`ALGORITHM_SEARCH_THRESHOLD`): 默认 0.1，用于搜索场景
+  - 较低阈值确保返回更多相关结果
+  - 适用于用户主动搜索图像时的广泛匹配
+
+- **推荐阈值** (`ALGORITHM_RECOMMEND_THRESHOLD`): 默认 0.2，用于推荐场景
+  - 较高阈值确保推荐质量
+  - 适用于系统自动推荐时的精准匹配
+
+#### 搜索策略
 1. **双路径搜索** (有主题时):
-   - 语义搜索路径 (70%): 保持语义相关性
-   - 主题搜索路径 (30%): 确保风格一致性
+   - 语义搜索路径 (70%): 保持语义相关性，使用搜索阈值
+   - 主题搜索路径 (30%): 确保风格一致性，使用搜索阈值
 
 2. **单一语义搜索** (无主题时):
-   - 使用原始提示词进行语义搜索
+   - 使用原始提示词进行语义搜索，使用搜索阈值
+
+#### 配置方式
+通过环境变量配置不同场景的阈值：
+```bash
+# 搜索场景阈值（更低，返回更多结果）
+ALGORITHM_SEARCH_THRESHOLD=0.1
+
+# 推荐场景阈值（更高，保证质量）
+ALGORITHM_RECOMMEND_THRESHOLD=0.2
+```
 
 ### 提示词优化
 系统会自动进行多层提示词优化：
@@ -602,9 +675,14 @@ type RecommendedImageResult struct {
 ## 性能优化
 
 ### 缓存机制
+- **项目上下文缓存**:
+  - 智能检查已有上下文，避免重复LLM调用
+  - 数据库持久化存储项目关键词
+  - 支持强制重新生成选项
 - **提示词分析缓存**: 避免重复AI分析调用
 - **推荐结果缓存**: 支持反馈功能的结果追踪
 - **向量服务**: 图像语义搜索的向量存储
+- **搜索阈值配置**: 分场景配置相似度阈值
 - **自动补全缓存**:
   - Trie树内存缓存（可选）
   - 支持缓存刷新和统计

spx-backend/.env.dev

@@ -33,6 +33,9 @@ OPENAI_MODEL_ID=
 # spx-algorithm service
 ALGORITHM_ENDPOINT=
 ALGORITHM_TIMEOUT=
+# Algorithm service thresholds
+ALGORITHM_SEARCH_THRESHOLD=0.1
+ALGORITHM_RECOMMEND_THRESHOLD=0.2
 
 
 # OpenAI (PREMIUM)

spx-backend/cmd/spx-backend/get_projects_context.yap

@@ -0,0 +1,32 @@
+// Get existing project context keywords (fast query for search).
+// Returns cached project context without LLM generation.
+//
+// Request:
+//   GET /projects/context?project_id=123
+
+import (
+	"strconv"
+	"github.com/goplus/builder/spx-backend/internal/controller"
+)
+
+ctx := &Context
+
+projectIDStr := ctx.FormValue("project_id")
+if projectIDStr == "" {
+	replyWithCodeMsg(ctx, errorInvalidArgs, "project_id is required")
+	return
+}
+
+projectID, err := strconv.ParseInt(projectIDStr, 10, 64)
+if err != nil || projectID <= 0 {
+	replyWithCodeMsg(ctx, errorInvalidArgs, "project_id must be a positive integer")
+	return
+}
+
+result, err := ctrl.GetProjectContext(ctx.Context(), projectID)
+if err != nil {
+	replyWithCodeMsg(ctx, errorNotFound, "project context not found")
+	return
+}
+
+json result

spx-backend/cmd/spx-backend/post_projects_context_generate.yap

@@ -1,4 +1,6 @@
-// Generate or update project context keywords.
+// Create or update project context keywords using LLM.
+// This endpoint will create new context or update existing context for a project.
+// Use force_regenerate=true to force regeneration even if context exists.
 //
 // Request:
 //   POST /projects/context/generate