Generated by Answer me with HTML 0.5.10 · 2026-11-05 21:45 · ★ Star on GitHub
视觉搜索抓取与来源展示:全栈技术方案
从创建任务到结果页与导出,贯通取数、执行、存储和展示。
1. 目标与改动
让视觉搜索结果页完整展示所选历史消息的 Prompt、拆 Query 和历史对话。 一份任务共享历史来源,各环境分别保存本次检索结果。 列表导出补齐三个来源字段,飞书历史统一使用 JSON 下载链接。
| 环节 | 改造前 | 改造后 |
|---|---|---|
| 历史取数 | 会话查询后直接构造图搜输入 | 增加消息明细查询,补充三个来源字段 |
| 任务数据 | 保留原有图搜输入和框坐标 | 在任务 penetrate 中增加 visual_search_source |
| 结果页 | 从各环境产物读取,来源不统一 | 视觉环境统一读取任务级来源 |
| 抓取执行 | 按图片和选框调用目标环境工具 | 延续原执行输入,新增字段用于来源展示 |
| 列表导出 | 未提供三个来源字段的独立导出列 | CSV 保留 JSON;飞书历史统一转 TOS 链接 |
2. 从提交到展示的完整链路
| 页面阶段 | HTTP 接口 | 职责 |
|---|---|---|
| 创建项目 | POST /admin/label/biz/add_evaluate_project/ | 保存来源和环境配置,取得 evaluate_id |
| 提交任务 | POST /admin/label/biz/create_tasks/ | 按来源参数启动取数和题目创建 |
| 查看结果 | GET /admin/label/get_evaluate_task_by_env/ | 返回任务元信息和环境产物 |
图中展示数据依赖,不表示 HTTP 请求会等待全部抓取完成。
3. 后端:Ekko 历史取数的两个 API
两个 API 都通过 dp.invoker.engine 的 QueryWithParams 调用。 API ID 是数据接口标识,下面分别简称“会话 API”和“明细 API”。
| 接口 | API ID | 输入 | 返回及用途 |
|---|---|---|---|
| 历史会话查询 | 7389155172762600485 | 日期、数量和来源配置;指定会话时带 session_id_list | 会话与 enc_message_str_list;从消息 JSON 取得 enc_message_id、query、图片和坐标 |
| 历史消息明细查询 | 7387617535350391817 | enc_message_id_list、日期及来源配置 | 当前消息的明细;取 image_prompt_info、search_query_list、history_5_rounds |
明细请求使用会话消息里的 enc_message_id。 不是根据 Query 文本重新搜索一条消息。 两个接口的 resp.Data 都是 JSON 字符串,先解码成记录数组。
Admin 先完成现有图片筛选,再为有效输入逐条查询明细。 明细必须只返回一条记录,且 enc_message_id 与请求一致。
| 数据名称 | 来自哪里 | 在本链路中的用途 |
|---|---|---|
| GQuery.QueryMulti → TaskInfo.QueryList | 会话消息里的 query | 构造本次执行输入 |
| visual_search_source.search_query_list | 明细 API | 展示历史拆 Query |
| crawl_result[i].query_list | 目标工具返回的 documents | 展示本次环境检索结果 |
会话 API 和明细 API 用于取历史数据。 Crawl 随后调用目标环境的视觉搜索工具,得到本次 documents。 当前 MCP 请求使用图片和选框,按原规则合并环境参数。 history_5_rounds 可包含历史回答和引用,但不作为本次工具结果。
4. 数据契约与产物归属
来源先写入 QueryInfo.Penetrate,随题目创建保存。 Legacy 路径保存到任务 Extra;Biz 路径保存到 PenetrateJSON。 任务详情统一返回 data.task.penetrate,类型仍是 JSON 字符串。
以下层级表示 JSON.parse(data.task.penetrate) 的结果。
- image_prompt_info对象或 null
- queryJSON 字符串,内容是 block 数组
- ImageUrl历史输入图片地址
- search_query_list字符串数组或 null
- history_5_rounds消息数组或 null
- 每条消息
- enc_message_id消息标识
- user_type1 为用户,2 为助手
- content_type当前 block 消息为 9999
- message_contentJSON 字符串,内容是 block 数组
- 每条消息
| 数据 | 保存与返回方式 | 前端读取位置 |
|---|---|---|
| 历史来源 | 创建题目时保存,不依赖抓取结果回传 | JSON.parse(data.task.penetrate).visual_search_source |
| 框坐标 | 保留任务级 b_box | JSON.parse(data.task.penetrate).b_box |
| 环境检索结果 | 工具响应形成产物,沿现有链路保存到 TOS | 当前环境的 crawlResult |
现有产物补充逻辑还会复制任务 penetrate,并平铺其中的字段。 因此 crawl_result[i].penetrate 和 crawl_result[i].visual_search_source 可能出现副本。 来源展示只读任务级字段,不在副本之间寻找或合并数据。
来源 JSON 的保存与复制,不等于转存其中的图片或附件。 本次来源透传没有增加对这些资源的逐项下载和转存。
5. 前端:只改视觉环境的来源展示
生效条件是当前环境 search_config.identity === "visual"。 同题保留各环境分栏;多个视觉环境展示同一份来源。 其他环境继续走既有取值和渲染路径。
下表中的 source 指任务级 visual_search_source。
| 展示区域 | 取值 | 渲染方式 |
|---|---|---|
| Prompt 正文 | source.image_prompt_info.query | 解析 block,复用现有渲染能力 |
| Prompt 图片 | source.image_prompt_info.ImageUrl | 展示图片,沿用选框绘制 |
| 框坐标文本 | task penetrate.b_box | 直接展示,不从浮点坐标重新拼接 |
| Query | source.search_query_list | 按原顺序展示;空值保留标题、正文留白 |
| 历史对话 | source.history_5_rounds | 按角色和顺序复用 ChatCore 与 block 渲染 |
| 图片参考信息 | 当前环境 crawlResult | 继续展示本次环境的检索结果 |
来源适配函数统一解析字段,组件消费适配结果。 历史保留连续用户消息,不转换成 req/res 配对结构。 历史消息显示轮次;没有可复制文本时不展示复制按钮。 历史内容使用 render 回调,普通刷新保留内部展开状态。
6. 关键设计与异常边界
| 设计 | 处理方式 | 原因 |
|---|---|---|
| 任务级保存来源 | 一题一份,多个视觉环境共享 | 来源属于所选历史消息,环境结果属于本次执行 |
| 保持执行输入 | 仍由会话 API 的消息构造 | 本次补齐展示数据,不替换图搜输入 |
| 历史上下文 | history_5_rounds 用于来源展示与导出 | 本期不把历史消息附加到搜索工具请求 |
| 后端 JSON 边界 | 三字段分别解开外层 JSON 编码 | query 和 message_content 留给前端按 block 解析 |
| 单字段异常 | 该字段返回 null,保留其余字段 | 展示信息异常不阻断已有有效输入抓取 |
| 整份明细不可用 | 查询失败、数量或消息 ID 不符时,三字段为 null | 不挂载身份不明的消息明细 |
后端是否取明细,由来源 Handler 决定。 当前分支要求 DouBaoSessionHandler 命中 doubao_visual_search 前缀。 前端是否展示来源,由环境 identity 决定。 两处条件分别控制取数与展示,不能互相替代。
日志以 stage=source_info 记录三字段状态和字节数。 stage=visual_input_ready 记录来源数、产出数和跳过数。 完整透传值从任务详情响应查看。
7. 抓取列表导出:字段配置与文件转存
导出读取任务已保存的三个来源字段。 飞书中的 history_5_rounds 有值就转为 JSON 文件下载链接。 短历史、长历史和空数组 [] 使用同一规则。 CSV 始终保留完整 JSON,任务详情中的来源结构保持不变。 本节以 Admin 提交 f4140a04f 为准。
页面与导出接口
| 接口 | 作用 | 关键参数或返回 |
|---|---|---|
| GET /admin/label/export/conf_list | 动态加载可选字段 | ConfList 中的 EName、DataIdx、EngineName |
| GET /admin/label/download_query_file_v2/ | 创建后台导出记录 | evaluate_id、export_key_list、request_id、record_export=1 |
| GET /admin/label/crawl_export/list/ | 查询项目导出记录 | evaluate_id、page、page_size |
| GET /admin/label/crawl_export/detail/ | 查询一条导出进度和结果 | export_job_id;成功后返回 result_url |
export_key_list 是 ename 数组的 JSON 字符串。 CSV 使用 file_type_v2=0、output_format=csv。 飞书表格使用 file_type_v2=1、output_format=lark_bitable。 导出范围沿用当前的勾选题目、筛选条件和项目全量逻辑。
三个字段从哪里读取
Exporter 将任务 Extra.Penetrate 解析成 task_info_penetrate。 Biz 任务经现有投影后使用同一导出结构。 导出不重新调用会话 API 或明细 API。
| ename | 完整 data_idx |
|---|---|
| image_prompt_info | task_info_penetrate.visual_search_source.image_prompt_info |
| history_5_rounds | task_info_penetrate.visual_search_source.history_5_rounds |
| search_query_list | task_info_penetrate.visual_search_source.search_query_list |
三个配置项统一使用 engine_name=BaseExportEngine。 前端根据配置生成选项,不为三个字段新增顶层请求参数。
TCC 配置
在现有 conf_list 中追加三个对象,保留已有配置。 已有同名 ename 时更新原项,避免重复。 下面是 history_5_rounds 的配置示例。 其余两项按上表替换 ename、header_name 和 data_idx。
{ "ename": "history_5_rounds", "header_name": "history_5_rounds", "data_idx": "task_info_penetrate.visual_search_source.history_5_rounds", "engine_name": "BaseExportEngine", "classification_v2": "base_info", "active_app_list": ["65766316"], "no_need_export": false}| 国内 AIDP 环境 | TCC key |
|---|---|
| PPE | 8875_export_ppe_v2_aidp |
| 线上 | 8875_export_v2_aidp |
后端先判断 AIDP 流量,再按运行环境选择配置。 active_app_list 与项目应用取交集,控制导出时是否生效。 该配置不负责在其他项目的导出弹窗中隐藏选项。
CSV 与飞书的内容契约
| 字段或情况 | CSV | 飞书表格 |
|---|---|---|
| image_prompt_info | 完整 JSON 文本 | 完整 JSON 文本 |
| search_query_list | 完整 JSON 文本 | 完整 JSON 文本 |
| history_5_rounds 有值 | 完整 JSON 文本 | 完整 JSON 文件的 TOS 下载链接 |
| history_5_rounds 为 [] | 保留 [] | 下载内容为 [] 的 JSON 文件 |
| 来源缺失、null 或空白 | 空值或空白 | 单元格留空,不上传 TOS |
飞书中的历史列仍是文本字段,内容为下载 URL。 它不是飞书附件列,不需要改成附件类型。 旧任务没有来源值时,导出不会补查或自动回填。
JSON 文件如何转存
- 在飞书单元格构建阶段匹配完整 history 字段路径。
- 校验导出字符串是合法 JSON。
- 对完整字符串计算 SHA-256。
- 将完整字符串写入现有 TOS。
- 将下载 URL 写入飞书记录,保留导出数据原文。
crawl_exports/<projectId>/history_5_rounds/<sha256>.json上传设置 application/json; charset=utf-8。 Content-Disposition 指定下载文件名 history_5_rounds.json。 当前导出 Handler 缓存内容哈希与下载 URL。 同一 Handler 内的重复历史复用链接,不重复上传。 跨次导出使用稳定路径,不代表存在全局上传缓存。
“保留原文”指转存前的导出单元格字符串。 转存时不重排 JSON,不解析 message_content 内层字符串。 前面的任务解析已发生 JSON 解码与序列化。 因此不承诺与最初 Ekko 响应的空格和键顺序逐字节一致。
转存的对象只有历史 JSON 文件。 其中的图片 URL、引用和附件地址保持原值,不逐项下载资源。 CSV 写入不经过飞书单元格转换,不会被替换成链接。
异常、部署与复测
| 情况 | 行为或检查点 |
|---|---|
| JSON 非法或 TOS 上传失败 | 返回错误;不写无效链接,不静默截断 |
| 实时同步转存失败 | 记录临时错误,保留游标供下次重试 |
| PPE 配置已有新列,执行端没有对应列 | 核对执行日志中的 env、cluster 和实际加载的 TCC |
| 仅部署 default 集群 | 还需确认对应 PPE 环境的 file 集群有可用实例 |
| 已经生成的飞书表格混有 JSON 和链接 | 部署新版本后重新导出;旧表格不会自动改写 |
单元格转换由普通导出和分批导出共用。 此前 TooLargeCell 的批次减半重试,不能解决单条历史过大。 当前历史列统一转为链接,不再依赖长度阈值。 image_prompt_info 和 search_query_list 保持现有文本规则。
8. 代码入口与验收
| 责任 | 代码入口 |
|---|---|
| 导出字段与 TCC 加载 | Admin:ExportConfList、NewExportConfV2Aidp |
| 后台导出记录与执行 | Admin:createCrawlExportRecord、ExporterHandlerV2 |
| 历史 JSON 文件与飞书单元格 | Admin:uploadBitableHistoryJSON、bitableCellValue |
| 导出字段选择与 record-mode 请求 | 前端:useNewExportActions、createCrawlExportRecord |
| 来源路由、会话查询及图搜输入 | Admin:gpt_douyin_session.go |
| 明细查询、身份核对、字段归一化 | Admin:visual_search_session_detail.go |
| Query 转换与任务保存 | Admin:CustomizeQueryList |
| 工具请求和环境产物 | Crawl:McpVisualSearch |
| 视觉环境分支 | 前端:Search |
| 来源适配与 block 展示 | 前端:visual-search-source.ts、VisualSourceContent.tsx |
| 验收场景 | 预期 |
|---|---|
| 同题两个视觉环境与普通环境混排 | 视觉来源一致,各环境结果独立;普通环境保持原取值 |
| 对照明细 API 和任务详情 | 三字段对应同一条消息,JSON 类型与内容可追溯 |
| 图片消息、连续用户消息、带引用回答 | 顺序、角色和已有 block 内容正确展示 |
| 明细失败或单字段异常 | 有效抓取输入保留;来源字段按上述规则返回 |
| Query 为空、折叠后刷新 | Query 标题保留;历史展开状态不被普通刷新重置 |
| 三字段 CSV 导出 | 解析 CSV 后与任务来源 JSON 的值一致 |
| 飞书导出短历史、长历史及 [] | 历史列全部为链接;下载 JSON 与导出值一致 |
| 缺失来源与重复历史 | 缺失值留空;同次导出重复历史复用链接 |
| 转存失败与实时同步 | 导出返回错误;实时游标不推进 |
| PPE file 集群与字段配置 | 实际执行环境、集群和 TCC 与预期一致 |
前端实现已提交:8d53c03c,分支为 codex/visual-search-source-display。 已有 PPE 样本验证的是 Legacy 自动取数入口。 Biz 创建入口还需核对最终来源 Handler,并完成部署后的端到端验收。 旧任务不会自动补齐新增来源字段。
Admin 导出实现已推送:f4140a04f,分支为 codex/visual-search-two-stage-fetch。 格式和静态检查已通过,新增 Go 用例未在本地执行。 统一 TOS 规则需部署后重新导出验收,不代表已有表格已更新。