docs(blog): add share document (#47)

* Create 17. 实训营心得分享

Signed-off-by: Sky-Runner-Z <[email protected]>

Author: Sky-Runner-Z

2025/17. 实训营心得分享/share.md

@@ -0,0 +1,164 @@
+# SPX-Algorithm：构建多模态搜索服务的一些心得
+
+## 写在前面
+
+也是快到结营阶段了，关于我在实训营期间负责的 SPX-Algorithm 这个项目模块的设计思路，想着写个分享记录一下这段时间的心得体会。这个项目说起来其实就是个图文搜索服务，但做下来发现里面还挺有意思的，尤其是在架构设计和工程实践方面踩了不少坑，也有一些收获。
+
+## 项目背景和定位
+
+SPX-Algorithm本质上是一个图像搜索推荐模块。用户输入文本描述，系统从图片库里找出最相关的结果。听起来简单，但实际做起来发现挑战不少。
+
+传统的图片搜索主要靠标签匹配，但这种方式局限性很明显。图片的标签往往不够丰富，用户的表达又很灵活。所以我的目标很明确：用AI来理解文本和图片的语义，让搜索更智能。
+
+## 整体架构思路
+
+经过一段时间的摸索，最终采用了分层架构设计：
+
+```text
+API层 ← 对外接口，简洁易用
+协调层 ← 编排各种算法模块  
+服务层 ← 图文匹配 + 重排序
+数据层 ← 向量存储 + 用户反馈数据存储
+```
+
+### 为什么选择分层架构？
+
+1. **职责清晰**：每一层只关心自己的事情，降低耦合
+2. **易于扩展**：加新功能时只需要在对应层面改动
+3. **便于测试**：每层都可以独立测试和调试
+4. **未来团队协作**：不同人可以专注不同层面的开发
+
+## 核心模块设计
+
+### 图文匹配服务
+
+这是算法实现的核心模块，负责理解用户查询并召回相关图片。
+
+选择CLIP模型主要是因为它能把文本和图片映射到同一个语义空间。我们用的是OpenCLIP的ViT-B-32，512维向量输出。这个选择是经过权衡的：
+
+- 效果足够好，能理解复杂的语义关系
+- 推理速度快，满足线上服务需求
+- 社区成熟，资料多坑少
+
+向量存储用的Milvus，主要看中它对大规模向量检索的优化。
+
+### 重排序服务
+
+图文匹配召回的结果虽然相关，但排序质量还有提升空间。这时候就需要重排序来精调。
+
+我们采用 LTR 的思路，基于用户的真实反馈来训练排序模型。整个设计围绕"用户反馈闭环"展开：
+
+1. **反馈收集**：用户每次搜索后的点击行为都会被记录下来
+2. **训练数据构建**：从点击行为中提取pairwise训练样本，被选中的图片作为正样本，未选中的作为负样本
+3. **模型训练**：使用神经网络学习用户偏好模式
+4. **在线重排序**：训练好的模型对搜索结果进行重新排序
+
+这种设计的好处是能够持续学习用户偏好，越用越准。但也有挑战，比如冷启动问题、反馈噪声处理等。
+
+### 搜索协调器
+
+为了统一管理多个算法服务，我们设计了SearchCoordinator。它的作用是编排整个搜索流程：
+
+1. 调用图文匹配服务进行粗排召回
+2. 如果启用了重排序，调用重排序服务进行细排
+3. 返回最终的排序结果
+
+这个设计让我们能够灵活控制算法流程，比如可以随时开关重排序功能，方便做A/B测试。
+
+## API设计理念
+
+在接口设计上，我们遵循了"对外简洁，对内丰富"的原则，主要分为三类接口：
+
+### 资源管理接口 (`/v1/resource/`)
+
+- `POST /add`：添加单个资源
+- `POST /batch`：批量添加资源  
+- `POST /search`：基于文本的语义搜索
+- `POST /match`：基于图片的语义搜索
+
+### 用户反馈接口 (`/v1/feedback/`)
+
+- `POST /submit`：提交用户点击反馈
+- `GET /stats`：查看反馈统计信息
+- `GET /recent`：获取最近的反馈数据
+- `POST /train`：触发模型训练
+- `GET /model/status`：查看模型状态
+- `POST /model/enable|disable`：启用/禁用重排序
+
+### 内部调试接口 (`/v1/internal/`)
+
+- 向量数据管理：查看、搜索向量数据
+- 资源管理：列表查询、删除操作
+- 数据库状态：详细的系统状态信息
+
+这样设计的好处是业务方使用简单（只需要关心resource接口），反馈收集独立成模块（便于数据科学团队使用），同时我们内部有足够的工具来监控和调试系统。
+
+## 踩过的坑和解决方案
+
+### SVG处理问题
+
+我们的图片库有很多SVG格式的图片，但CLIP模型只能处理位图。最初直接用Pillow转换，发现效果很差——SVG的矢量信息丢失了。
+
+后来改用CairoSVG来处理，质量明显提升。
+
+这个经历让我意识到：**看似简单的问题往往有很多细节**。
+
+### 向量存储优化
+
+最初我们把所有向量数据都放在内存里，随着数据量增长很快就撑不住了。
+
+迁移到Milvus后，发现索引类型的选择很关键。我们试了IVF、HNSW等几种索引，最终选择HNSW是因为它在我们的数据规模下召回率和速度表现最均衡。
+
+### 重排序特征设计
+
+重排序模块我们改了好几版。最初用10维手工特征，包括余弦相似度、欧氏距离、向量模长等。后来发现CLIP向量已经归一化了，模长特征基本没用。
+
+最终改成了神经网络方案，用1500多维的丰富特征，包括原始向量、统计特征等。虽然维度高了很多，但信息保留更完整。
+
+### 配置管理混乱
+
+项目初期配置管理比较随意，开发、测试、生产环境的配置经常搞混。后来统一用dataclass重新设计了配置系统，按环境分离，清爽了很多。
+
+## 一些工程实践心得
+
+### 日志和监控
+
+每个关键模块都加了详细的日志，包括：
+
+- 请求响应时间
+- 数据库操作耗时  
+- 搜索结果统计
+- 异常情况记录
+
+这些数据在出问题时特别有用，能快速定位根因。
+
+### 错误处理
+
+对于算法服务来说，容错很重要。我们的策略是：
+
+- 单个服务出错不影响整体功能
+- 重排序失败时返回粗排结果
+- 向量服务异常时走降级逻辑
+
+### 测试策略
+
+除了常规的单元测试，我们还设计了端到端的功能测试。特别是对于机器学习模块，我们会构造一些已知结果的测试用例，确保算法逻辑正确。
+
+## 未来的一些想法
+
+1. **多模态融合**：除了CLIP，考虑加入其他视觉理解能力
+2. **个性化搜索**：结合用户历史行为做个性化排序
+3. **特征学习**：让模型能更好地适应用户偏好
+4. **效果评估**：建立更完善的线上效果评估体系
+
+## 总结
+
+做SPX-Algorithm这个项目最大的收获是：**好的架构设计比炫酷的算法更重要**。
+
+技术选型要务实，不要为了用新技术而用新技术。我们选择CLIP、Milvus这些相对成熟的方案，主要考虑的是稳定性和可维护性。
+
+工程实践要细致，很多看起来简单的问题往往有很多坑。配置管理、错误处理、日志监控这些"脏活累活"往往决定了系统能不能稳定运行。
+
+最后，用户反馈闭环很重要。我们通过收集用户的真实行为数据来持续优化算法效果，这比闭门造车要有效得多。
+
+希望这些分享对大家有用。如果有问题欢迎交流讨论！