企业官网建设流程全解析

SearchCLI 是面向火山引擎 AI Search 的开源命令行工具，其数据集管理能力是 AI 搜索落地的第一步。本文将带你用 8 个vs dataset命令，完整跑通数据集创建、数据导入与Schema 校验三大核心流程，帮助新手快速把一份业务数据变成可被搜索的数据集。

一、为什么数据集管理是 AI 搜索的起点？

在 SearchCLI 中，搜索（vs search run）、推荐（vs recommend run）、对话式检索（vs chat run）都运行在"应用 + 数据集"之上。数据集（Dataset）承载你的结构化业务数据，而 Schema 定义了哪些字段参与检索、哪些字段用于筛选。

一句话概括数据集的工作流：

准备数据(JSONL) → 创建数据集 → 导入数据 → 校验Schema → 绑定应用 → 发起搜索

本文聚焦前四步，覆盖以下 8 个命令：

命令实现入口见 product-commands.ts，全部命令速查可参考官方文档 docs/COMMANDS.md。

二、快速上手：两种数据集创建方式

方式 1：手动指定 Schema（schema-only 路径）

适合字段结构明确、想完全掌控数据集的人：

vs dataset create --name demo-items --type item --schema @schema.json

常用可选参数：

• --industry：行业提示，如e_commerce、video、news
• --language：语言提示，如zh、en
• --theme：主题提示，--type=multi_modal时必填，可选general|e_commerce|content|long_video
• --dry-run：只做服务端校验，不真正落库，强烈建议先跑一遍

仓库中提供了一份完整的创建载荷示例，包含 Schema 与 FieldDescMap，可直接参考：dataset-create.json。

方式 2：整包创建（推荐）

当你已经拥有dataset-create.json这类完整载荷时，直接整包提交，可以让 Schema 和 DataFieldConfig 保持一致：

vs dataset create --data @dataset-create.json

💡 新手提示：--name/--type/--schema适合手工建库；--data适合由工作流产出的完整载荷。两者二选一即可。

三、数据导入：一条命令完成 V2 全链路

vs dataset ingest是数据导入的核心命令，支持两种模式。

模式 1：V2 全链路入库（--file 模式）

vs dataset ingest --file ./items.jsonl --type item --industry e_commerce --language zh

这条命令会自动串联执行：预签名上传 → Schema 推断轮询 → 创建数据集。整个过程无需手动切换命令，加--dry-run还能先验证不落库。对于图文/视频类数据，还可以控制异常处理策略：

vs dataset ingest --file ./products.jsonl --type multi_modal \ --theme e_commerce --abnormal-image-policy skip --industry e_commerce --language zh

其中--abnormal-image-policy skip表示丢弃异常图片行，改为block则整次导入失败——生产环境建议用block保证数据质量。

模式 2：向已有数据集写入数据（--fields 模式）

数据集已建好，只写数据：

vs dataset ingest --dataset-id 123 --fields @items.json

仓库里有一份真实的 JSONL 商品数据样例，每行一个 JSON 对象，展示了 title、description、price、image_url 等典型字段：items.jsonl。

📌 数据来自数据库？可先用vs connector export --source mysql ...导出为本地 JSONL，再交给ingest --file，详见 COMMANDS.md 中 connector 部分。

四、Schema 推断与校验：4 步手动链路

ingest --file虽然一键全包，但理解底层链路能帮你排查问题。V2 入库的完整链路是：import-url → infer-schema → infer-result → create。

第 1 步：申请上传地址

vs dataset import-url --file-name items.jsonl

返回FileUrl与FileKey，把本地文件 PUT 到FileUrl即可。

第 2 步：提交 Schema 推断任务

vs dataset infer-schema --tos-key onboarding/items.jsonl --type item

提交后返回TaskID。可以顺带提供--industry、--language等提示，提升推断准确度。

第 3 步：轮询推断结果

vs dataset infer-result --task-id task_abc123

Status会从Pending/Running变为Success或Failed。成功后返回 Schema、FieldDescMap 和 DataFieldConfig，样例结果可参考 infer-result.json。

第 4 步：本地校验与可视化确认

vs dataset validate-schema --input ./infer-result.json --dataset-type multi_modal

该命令在本地渲染出可读的 Schema 确认块（字段表、字段角色、告警），无需再发请求。类型参数决定校验规则：

• multi_modal：校验主键 BizAttr、IndexFields 与角色引用
• user_event：行为数据集使用不同的主键机制，跳过上述检查

⚠️ 常见坑：infer-result是单次调用，不自动轮询；ingest --file模式才内置了轮询逻辑。手动链路下需要自己重复执行第 3 步直到Success。

五、日常管理：list / get / update / delete

建完库之后的日常操作：

vs dataset list # 列出全部数据集 vs dataset list --type item --name demo # 按类型/名称过滤 vs dataset get --id 123 # 查看单个数据集 vs dataset get --id 123 --full # 返回原始完整响应

维护类命令（不属于本文 8 命令但高频使用）：

• vs dataset update --id <id> [--version <n>] [--description <text>] [--schema @schema.json]：更新描述或 Schema 版本
• vs dataset delete --id <id> [--force]：删除数据集

update 命令实现见 update.ts，delete 命令见 delete.ts。

六、新手避坑清单

1. 先 dry-run，后真跑：create和ingest都支持--dry-run，先验证载荷再落库，避免白建库。
2. multi_modal 必须带 theme：--type=multi_modal时--theme是必填项，否则参数校验直接报错。
3. type 取值别搞混：类型只允许user_event或multi_modal，行业别名如ecommerce会被自动规范为e_commerce。
4. 别手写 Schema 猜字段：优先用ingest --file全链路让服务推断，再用validate-schema本地复核，效率更高。
5. 异常数据策略要显式声明：默认行为在不同场景风险不同，skip与block请按数据质量情况明确选择。

七、延伸学习

• 全部命令与参数速查：docs/COMMANDS.md
• 数据集命令帮助文案与默认值定义：src/app/product-commands.ts
• V2 入库验收测试脚本（含完整链路调用）：scripts/suites/v2-onboarding.cjs
• 更多入库示例与技能文档：skills/vs-item-onboarding/SKILL.md

掌握以上 8 个命令后，你可以从一份 JSONL 数据出发，独立完成数据集创建、数据导入和 Schema 校验，为后续的vs search run搜索验证打好基础。