Rails Rails 技术实战之 AI 找货小助手设计

ThxFly · 2026年02月10日 · 34 次阅读

AI 找货助手技术实现指南

最近阿里云千问的"点奶茶"技能很火，碾压了微信红包的 AI 玩法。这波 AI 热潮下，我们在 APP 里也做了一个 AI 找货功能。

用户搜"温润的手镯"，传统搜索只认"温润"和"手镯"两个字。但用户真正想要的是和田玉——因为"温润"是和田玉的特征。

这篇讲讲怎么用向量搜索 + AI 对话，让系统理解用户真正想要什么。淘宝、京东、美团、携程都有类似功能，我们这个还比较粗浅，讲个大概，体验看起来还有待优化，还请包涵。

需求预览

核心概念

概念	说明
Dify	开源 LLM 应用开发平台，我们用它做工作流编排。Dify 部署成独立服务，Rails 后端通过 HTTP API 调用。
SSE	Server-Sent Events，服务器主动推送数据给前端，比 WebSocket 简单，适合这种单向实时推送的场景。
向量搜索	把文本转成 1024 维向量，算向量相似度来找商品。比如"温润的手镯"能匹配到"和田玉手镯"。
KNN	K 最近邻算法，在向量空间里找最相似的 K 个商品。K 越大结果越多，但也越慢。
Embedding	把文本转成向量的过程，语义相近的文本向量也相近。
HNSW	一种高效的向量索引算法，ES 8.x 原生支持，用来加速 KNN 搜索。

一、技术架构总览

1.1 整体架构图

整体流程

用户在前端输入需求 → SSE 建立长连接 → Rails 把请求转给 Dify → Dify 识别意图、提取参数 → Dify 调用 Rails 的搜索接口 → Rails 生成查询向量 → ES 做 KNN 向量搜索 → 结果沿路返回 → 前端展示。

几个关键点

前端和 Rails 之间用 SSE，服务器主动推送，不用轮询。
Dify 是外部服务，Rails 只负责转发和调用搜索接口。
搜索用的是向量搜索，不是传统的关键词匹配。

核心配置

配置项	环境变量	作用
Dify API 地址	`DIFY_API_BASE_URL`	Dify 服务的 URL
Dify API Key	`DIFY_CHATFLOW_API_KEY`	调用工作流的认证密钥

核心接口

接口	路径	谁调用
SSE 对话接口	`POST /api/v1/chat/stream`	前端
商品语义搜索接口	`POST /api/v1/products/ai_search`	Dify 工作流

1.2 商品列表接口

GET /api/v1/products 这个接口支持两种搜索方式：普通搜索（传 q、category_id、price_min/max 等参数），和 ai_search_id 搜索（传之前搜索的 ID，复用搜索参数）。

使用场景是这样的：用户在对话里看到商品列表，想看更多，点"查看更多"按钮，前端把之前的 ai_search_id 传过来，后端直接从数据库捞出之前的搜索参数，做分页查询。

1.3 数据流转

两个关键点

商品向量是上架时生成的，存在 ES 里；查询向量是每次搜索实时生成的。
向量生成失败了怎么办？降级处理，返回空结果或者转关键词搜索。

1.4 技术栈

组件	选型	说明
工作流引擎	Dify	最新版，做 AI 流程编排
LLM	通义千问 qwen-plus-latest	意图理解、参数提取
搜索引擎	Elasticsearch 8.x	商品索引 + KNN 向量搜索
后端框架	Ruby on Rails 8.x	业务逻辑

二、SSE 事件设计

2.1 事件流程图

2.2 事件类型

事件类型	触发时机	作用
`system_message`	连接建立后、stream_end 前	系统提示，比如"正在匹配货品中"，或者错误提示
`message_start`	第一次收到 Dify 的 message	告诉前端准备接收消息
`message`	收到 Dify 的 message	真正推送内容，可能拆成多个片段
`thought`	Dify 节点开始处理	显示"正在处理：xxx"，让用户知道进度
`message_end`	收到 Dify 的 message_end	一条消息发送完成
`stream_end`	整个流程结束	前端可以关闭连接了

msg_type 的取值

message_start 和 message 的 msg_type：

Dify 返回 PRODUCT_CARD → product_card（商品卡片）
Dify 返回 CLARIFY_CARD → clarify_card（追问卡片）
Dify 返回 TEXT → text（普通文本）
其他情况默认 text，结构化内容可能是 blocks

system_message 的 msg_type：

show_thinking：显示思考过程
hide_thinking：隐藏思考过程
text：普通系统文本
retry：可重试的错误

2.3 事件数据格式

message_start

{
  "event": "message_start",
  "data": {
    "msg_id": "uuid",
    "msg_type": "text",
    "role": "assistant",
    "task_id": "uuid"
  }
}

message

{
  "event": "message",
  "data": {
    "msg_id": "uuid",
    "content": "这是消息内容",
    "task_id": "uuid"
  }
}

message_end

{
  "event": "message_end",
  "data": {
    "msg_id": "uuid",
    "status": "success",
    "usage": {
      "prompt_tokens": 100,
      "completion_tokens": 50,
      "total_tokens": 150
    }
  }
}

stream_end

{
  "event": "stream_end",
  "data": {
    "conversation_id": "uuid",
    "status": "success"
  }
}

system_message

{
  "event": "system_message",
  "data": {
    "id": "uuid",
    "msg_type": "text",
    "role": "system",
    "content": "正在匹配货品中",
    "user_message_id": 123
  }
}

thought

{
  "event": "thought",
  "data": {
    "msg_id": "uuid",
    "content": "正在处理：属性提取",
    "task_id": "uuid"
  }
}

2.4 事件顺序和处理规范

标准顺序

连接建立后，先发 system_message（show_thinking）告诉用户"正在匹配"
收到 Dify 的 message，第一次发 message_start，然后发 message（可能多次）
收到 node_started 时可以发 thought
收到 message_end 时发 message_end
有系统消息（错误或提示）发 system_message
最后发 stream_end

错误处理

错误不走单独的 error 事件，统一用 system_message
msg_type 是 retry 表示可重试的错误
不管成功失败，最后都会发 stream_end

前端注意事项

message 是流式的，前端要累积内容直到收到 message_end
根据 msg_type 决定怎么渲染
收到 stream_end 就关闭连接

三、Dify 对话流设计详解

3.1 工作流核心结构

我们用 Dify 的节点式编排来做对话流，核心节点如下：

节点类型	作用
Start	接收用户输入和认证信息
Question Classifier	意图识别，分成 4 种意图
LLM	属性提取，把用户输入转成结构化参数
If-Else	判断要不要追问用户
LLM	生成追问话术和选项按钮
HTTP Request	调用后端搜索接口
Code	结果合并，各分支互斥，只返回其中一个结果

工作流里的变量：环境变量 HTTP_DOMAIN 存 API 域名。

3.2 Start 节点

起点，接收前端传来的变量：

变量	类型	说明
intent	string	用户意图标识
authorization	string	Bearer Token
version_date	string	版本日期（可选）

3.3 意图识别

用 Dify 的 Question Classifier 节点，把用户请求分成 4 类：

分类 ID	名称	例子
1	找货意图	"找翡翠手镯"、"想买和田玉"
2	知识问答	"怎么鉴别翡翠 A 货"、"如何保养和田玉"
3	App 问答	"怎么注册账号"、"如何发布商品"
4	闲聊	"你好"、"谢谢"、"再见"、"今天天气怎么样"

模型配置：通义千问 qwen-plus-latest，Temperature 设 0.3 保证分类稳定，对话记忆保留最近 10 轮。

3.4 属性提取

从用户输入里提取搜索参数，用 LLM 节点，模型也是通义千问，Temperature 0.3。

q 字段（核心搜索描述）

要包含明确的商品品类词
50-100 字的自然语言描述
有些默认规则：用户说"玉石"没具体说是和田玉还是翡翠，默认当和田玉处理；说"高货"默认当翡翠处理。

价格范围

price_min 只有满足"品类 + 高价值信号 + 高价值形态 + 无瑕疵"时才推断。比如用户说"高品质玻璃种翡翠手镯，无纹无裂"，才可能推断最低价。

price_max 按用户字面描述来，用户说"5000 元左右"就设 5000。

分类映射

1=>翡翠，2=>玉石，3=>钻石，4=>彩宝，39=>书画，40=>黄金，107=>黄金饰品，109=>文玩古玩，110=>钱币邮票

输出字段

字段	类型	必填	说明
q	string	是	核心搜索描述
price_min/max	number/null	否	价格范围（元）
category_id	number/null	否	商品分类 ID
inner_circle_size_min/max	number/null	否	圈口尺寸（mm）
heat_min/max	number/null	否	参与热度范围
is_uncertain	boolean	否	是否模糊需追问
has_discount	boolean	否	是否要优惠商品
negative_filters	array[string]	否	排除关键词

3.5 条件判断

检查 is_uncertain 字段，true 就进入追问分支，false 直接搜索。

触发追问的例子

"想买个手镯" → 缺少价格、材质，追问
"5000 元的" → 缺少商品类型，追问
"翡翠手镯，5000-8000 元" → 信息完整，直接搜

3.6 生成追问

当需要追问时，用 LLM 生成话术和选项。Temperature 设 0.7 高一点，让回答更有创造性。

生成规则：message 字段要共情 + 归因 + 引导，suggested_questions 至少 3 个肯定式选项。

{
  "message": "追问话术",
  "suggested_questions": [
    { "title": "问题标题", "intent": "find_item" }
  ]
}

3.7 HTTP 请求节点

真正调用 Rails 搜索接口的地方：

POST 请求
URL：{{#env.HTTP_DOMAIN#}}/api/v1/products/ai_search
请求头带 X-Authorization（从 Start 节点取）

超时和重试：连接/读取/写入都设 10 秒，失败自动重试 1 次。

3.8 结果合并

根据条件判断走不同的分支，各分支互斥，只返回其中一个：追问分支返回追问话术，搜索分支返回商品列表结果，无结果时返回默认话术。

四、向量搜索技术详解

4.1 为什么用向量搜索

传统搜索的局限：

搜索方式	问题
关键词搜索	无法理解语义，"温润的手镯"匹配不到和田玉
短语匹配	要求太精确，用户不会打完整短语
布尔搜索	AND/OR/NOT 组合太复杂，用户不会用

向量搜索能理解语义：

搜什么	关键词搜索	向量搜索
"温润的手镯"	匹配含"温润"和"手镯"的商品	匹配和田玉手镯
"高货"	匹配含"高货"的商品	匹配翡翠高品
"送妈妈的礼物"	几乎没结果	匹配适合送长辈的手镯

4.2 向量搜索原理

流程：文本 → Embedding 模型 → 1024 维向量 → KNN 搜索 → 返回结果。

步骤：1) 把用户输入转成向量；2) 在 ES 里用余弦相似度找最相似的 20 个商品；3) 用 min_score 阈值过滤。

4.3 EmbeddingService 实现

我们用阿里云百炼的 Embedding 接口。一次请求把文本转成 1024 维向量，耗时大概 100-200ms。

缓存策略：相同文本 10 分钟内重复查询直接返回缓存。

错误处理：向量生成失败了返回空数组，后面的 ES 查询就不做了，避免浪费资源。

vector = EmbeddingService.encode("翡翠手镯，种水细腻，色泽温润")
# => [0.023, -0.156, 0.089, ..., 0.012] (1024个浮点数)

4.4 商品向量同步 Job

商品上架后，AI 总结生成完成时自动触发向量生成。流程：

取商品的 AI 总结（必须是已生成的）
组合文本：商品标题 + AI 总结内容
调用 EmbeddingService 生成 1024 维向量
验证向量维度
同步到 ES 的 ai_summary_vector 字段
标记生成时间 vector_generated_at

注意事项：版本冲突自动重试 3 次，失败了要报警。向量是预先生成的，搜索时直接用，不用实时生成。

4.5 ES KNN 查询构建

核心方法：

方法	作用
`build_ai_knn_search_body`	构建 KNN 查询 Body
`extract_knn_filters`	提取过滤条件（排除关键词、圈口尺寸等）
`apply_filters_to_knn_query`	应用过滤条件

关键参数

k：返回多少条结果。翡翠设 30，玉石 25，钻石和彩宝设 20。翡翠商品多，设大一点有足够候选。
min_score：相似度阈值。翡翠设 0.85，玉石 0.8。翡翠商品描述比较标准化，设高一点不容易跑偏。

核心词加权：如果提取到核心词（如"翡翠"），生成向量时重复 3 次，让这个词权重更高。"翡翠手镯" → "翡翠翡翠翡翠手镯" → 生成向量。

4.6 召回、排序、重排

召回流程

生成查询向量
用 HNSW 在向量空间里找最近的 k 个
应用 knn.filter 过滤条件
计算余弦相似度，过滤低于 min_score 的
返回商品 ID 列表

排序：目前只用 _score（相似度分数）降序，简单的做法，后续可以加其他排序维度。

重排：没有额外的重排逻辑，ES 返回什么顺序就是什么顺序。

4.7 完整 ES KNN 查询示例

{
  "knn": {
    "field": "ai_summary_vector",
    "query_vector": [0.023, -0.156, 0.089, 0.234, -0.067, 0.178, ..., 0.012],
    "k": 20,
    "filter": {
      "bool": {
        "filter": [
          { "term": { "category_id": 1 } },
          { "term": { "status": "onsale" } },
          { "term": { "hide_in_miniprogram": false } },
          { "range": { "confirmed_price": { "gte": 5000, "lte": 7000 } } },
          { "range": { "inner_circle_size": { "gte": 55, "lte": 58 } } },
          { "exists": { "field": "ai_summary_vector" } }
        ],
        "must_not": [
          { "match_phrase": { "goods_description_text": { "query": "镶嵌", "analyzer": "ik_max_word" } } }
        ]
      }
    }
  },
  "min_score": 0.8,
  "from": 0,
  "size": 10,
  "sort": [
    { "_score": { "order": "desc" } },
    { "updated_at": { "order": "desc" } }
  ]
}

说明：过滤条件都在 knn.filter 里处理，在向量搜索阶段就过滤，减少计算量。

五、商品语义搜索模块详解

5.1 AiSearch 数据模型

AiSearch 表记录每次搜索的完整参数，搜索条件用 JSONB 存。为什么要冗余存一份 keywords_text？因为运营同学要统计数据，JSONB 查起来麻烦。每条记录关联 ai_chat_id 和 ai_chat_message_id，方便回溯"这条搜索结果是谁发的"。

主要字段

字段名	类型	说明
msg_id	string	消息 ID（唯一索引）
search_params	jsonb	完整搜索参数
keywords_text	string	搜索关键词文本（冗余字段）
category	string	商品分类（冗余字段）
price_min/max	decimal	价格范围（冗余字段）
ai_chat_id	bigint	关联的对话 ID
ai_chat_message_id	bigint	关联的消息 ID

使用场景：记录搜索参数支持"再次搜索"，通过 ai_search_id 复用参数实现"查看更多"，也支持搜索行为分析和统计。

5.2 API Controller 实现

POST /api/v1/products/ai_search

处理流程

参数校验：q 或 category_id 至少一个不为空
创建 AiSearch 记录，生成 ai_search_id
执行搜索：生成查询向量 → 构建 KNN 查询 → ES 查询
数据组装：从数据库捞商品详情，用 Presenter 格式化
返回结果：带 ai_search_id、total、products

成功返回

{
  "success": true,
  "data": {
    "ai_search_id": "uuid",
    "total": 15,
    "products": [
      { "id": 12345, "title": "翡翠手镯", "price": 6000, ... }
    ]
  }
}

错误返回

{
  "success": false,
  "error": "参数错误：q 或 category_id 不能为空"
}

curl 调用示例

curl -X POST "https://api.example.com/api/v1/products/ai_search" \
  -H "X-Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{"is_ai_search": true, "q": "翡翠手镯，5000-8000元", "category_id": 1, "price_min": 5000, "price_max": 8000}'

错误处理

错误类型	处理方式
参数校验失败	返回 400，提示具体错误信息
向量生成失败	记录日志，返回空结果
ES 查询失败	返回 500，提示"搜索失败，请稍后重试"

六、KNN 按分类配置

配置表：ai_search_knn_category_config

分类 ID	分类名称	k	min_score
1	翡翠	30	0.85
2	玉石（和田玉等）	25	0.8
3	钻石	20	0.82
4	彩宝	20	0.8

k：返回多少条结果。翡翠商品多，设 30；其他品类设 20-25。

min_score：相似度阈值。翡翠设 0.85 因为商品描述标准化，不容易跑偏；其他品类设 0.8。

调参建议：搜索结果太少就降 min_score 或增 k；结果不相关就提高 min_score。如果某个分类经常没结果，可以把 min_score 降 0.05-0.1。

七、常见问题与故障排查

7.1 SSE 连接问题

现象：SSE 连接建立失败或频繁断开

排查步骤

检查请求头：Accept: text/event-stream
检查 token：X-Authorization: Bearer <token>
检查网络和代理设置
看 Rails 日志里的错误信息

常见原因：token 过期或无效、网络超时（默认 60 秒）、服务器主动关闭连接。

7.2 向量生成失败

现象：搜索返回空结果

排查步骤

检查 Embedding 服务 API 是否可访问
检查 API 密钥是否有效
看 Rails 日志的错误信息
检查缓存是否正常（失败的请求也可能被缓存）

解决：向量失败会降级为返回空结果，检查 Embedding 服务配置和网络，清理缓存后重试。

7.3 Dify 工作流调用失败

现象：调用超时或返回错误

排查步骤

检查 DIFY_API_BASE_URL 环境变量
检查 DIFY_CHATFLOW_API_KEY 是否有效
检查 Dify 服务是否正常
看 Rails 日志的详细错误

常见错误：ConnectionError（连不上 Dify）、ResponseError（Dify 返回错误）、ParseError（响应解析失败）。

7.4 ES 查询慢

现象：查询超时或延迟高

排查步骤

检查 ES 集群状态和负载
检查索引分片和副本配置
检查 k 值是否过大（建议不超过 50）
检查 HNSW 参数

优化：适当降低 k、缩小 knn.filter 范围、检查 ES 集群资源。

7.5 搜索结果不相关

现象：返回的商品和用户需求不匹配

排查步骤

检查 Dify 提取的 q 字段是否正确
检查 ES 里的 ai_summary_vector 是否正常
检查 min_score 阈值是否合适
检查核心词加权是否生效

解决：提高 min_score、检查商品 AI 总结质量、优化属性提取规则。

技术架构总结

┌─────────────────────────────────────────────────────────────
│                    AI 找货助手技术架构                         
├─────────────────────────────────────────────────────────────
│  前端层 → SSE 对话接口 → Dify 工作流 → 商品语义搜索接口       
│                              ↓                               
│                      Elasticsearch KNN 搜索                   
│                              ↓                               
│                      商品向量同步 + 查询向量生成               
├─────────────────────────────────────────────────────────────
│  核心流程：Dify 对话流 → 意图识别 → 属性提取 → 追问 → 搜索     
│  核心技术：SSE 实时推送 + 向量语义搜索 + HNSW 高性能索引       
└─────────────────────────────────────────────────────────────

1 个赞

暂无回复。

需要登录后方可回复, 如果你还没有账号请注册新账号

Rails Rails 技术实战之 AI 找货小助手设计

Rails Rails 技术实战之 AI 找货小助手设计

AI 找货助手技术实现指南

需求预览

目录

核心概念

一、技术架构总览

1.1 整体架构图

1.2 商品列表接口

1.3 数据流转

1.4 技术栈

二、SSE 事件设计

2.1 事件流程图

2.2 事件类型

2.3 事件数据格式

2.4 事件顺序和处理规范

三、Dify 对话流设计详解

3.1 工作流核心结构

3.2 Start 节点

3.3 意图识别

3.4 属性提取

3.5 条件判断

3.6 生成追问

3.7 HTTP 请求节点

3.8 结果合并

四、向量搜索技术详解

4.1 为什么用向量搜索

4.2 向量搜索原理

4.3 EmbeddingService 实现

4.4 商品向量同步 Job

4.5 ES KNN 查询构建

4.6 召回、排序、重排

4.7 完整 ES KNN 查询示例

五、商品语义搜索模块详解

5.1 AiSearch 数据模型

5.2 API Controller 实现

六、KNN 按分类配置

七、常见问题与故障排查

7.1 SSE 连接问题

7.2 向量生成失败

7.3 Dify 工作流调用失败

7.4 ES 查询慢

7.5 搜索结果不相关

技术架构总结