Embedding 测试
面向开发者的 Embedding API 交互式调试场 —— 让向量化模型不再"黑盒"。
欢迎来到 Embedding 测试 工具。如果你正在做 RAG（检索增强生成）、语义搜索或任何与向量嵌入（Embedding）相关的工作，那么这个工具会成为你迭代模型选择、验证召回效果的好帮手。
你可以把它想象成 Embedding 模型的"示波器"——既能输出原始信号（原始 API 响应），也能做数据对比分析（语义距离排行榜），还能直接模拟完整的 RAG 检索链路。
快速上手
在使用前，请确保你已经在应用的"设置 > LLM 配置"中配置好了至少一个支持 Embedding 的模型服务（如 OpenAI text-embedding-3-small、本地部署的 bge-m3 等）。
第一步：选择 Embedding 模型
打开 Embedding 测试工具后，在顶部右侧的模型选择器中选中你配置好的 Embedding 模型。
TODO: 截图 - 顶部模型选择器
第二步：选择一个测试模式
工具提供了三个 Tab，你可以根据当前需求选择：
- 相似度对比 —— 验证模型对语义相近/相远概念的区分能力
- 检索模拟 —— 搭建微型知识库，模拟 RAG 召回过程
- 基础调试 —— 查看原始 API 响应，验证模型接入是否正常
建议新手先从 相似度对比 开始，感受 Embedding 模型的"语义直觉"。
功能详解
🎯 相似度对比
这是你快速评估 Embedding 模型语义理解能力的最佳入口。
典型使用场景：
你正在对比 text-embedding-3-small 和 text-embedding-3-large 对中文语义的区分能力，想知道哪个模型更理解"机器学习"和"神经网络"之间的联系，又不会把"红烧肉"当成相关概念。
操作步骤：
- 在左侧"对比设置"区域，选择一种对比算法（默认余弦相似度，通常是最常用的语义指标）。
- 在"基准文本"编辑器中输入你关注的中心概念，例如
"计算机科学"。 - 在"对比文本组"中，列出一批你想测试的词汇或短句（系统已预置了 9 条示例文本，你可以随意增删改）。
- 点击 "开始对比"。
- 右侧"语义相似度排行"面板会立即按相似度从高到低展示结果。
结果解读：
每条结果卡片包含：
- #排名 —— 序号，从高到低排列
- 相似度分数 ——
0.0000~1.0000之间的数值，越接近 1 表示语义越相近 - 背景进度条 —— 可视化相似度百分比
- 颜色编码 —— 绿色（> 0.8）高度相关、黄色（> 0.5）中等相关、红色（≤ 0.5）低相关
你可以点击结果面板右上角的复制按钮，一键将排行榜复制到剪贴板，方便分享或记录。
💡 小技巧：你可以随时切换对比算法（余弦 / 欧氏 / 点积 / 曼哈顿），系统会自动基于已缓存的向量重新计算分数，无需重新请求 API。这让你能在同一组向量上直观对比不同距离指标的表现。
🗂️ 检索模拟
这是模拟 RAG 系统 Retrieval 阶段的最佳环境——无需搭建任何后端，纯前端即可体验完整的"文档索引 → 查询召回"流程。
典型使用场景：
你想验证自己的知识库文档经过某个 Embedding 模型后，针对特定查询的召回效果。例如构建一个"AI 工具库"小知识库后，输入"如何构建桌面应用"看能否准确召回 Tauri/Rust 相关的文档。
操作步骤：
1. 构建知识库
在左侧"模拟知识库"面板中：
- 点击 "＋" 按钮添加文档片段
- 在弹出的编辑器中输入文档内容
- 重复以上步骤，建立你的微型知识库
系统已预置了 12 条覆盖技术、科学和文化的示例文档，你可以直接体验。
2. 一键向量化
编辑完文档后，点击 "一键向量化" 按钮。系统会批量调用 Embedding API，为每篇文档生成向量。成功向量化的文档左侧会显示绿色边框标记。
3. 执行检索
在右侧的检索区域：
- 输入你的查询语句，例如
"如何构建桌面应用程序？" - 配置检索参数：
- Top-K：返回前 N 条匹配结果
- 相似度算法：选择距离计算方式
- 搜索阈值：通过滑块设定相似度下限，低于此分数的结果将被过滤
- 按回车或点击 "检索" 按钮
4. 查看召回结果
右侧会展示命中的文档卡片，包含：
- 排名标记（TOP 1 / TOP 2 ...）
- 相似度百分比 和进度条
- 文档原文内容
💡 小技巧：当知识库向量化完成后，你可以修改查询语句反复测试召回效果，系统会自动缓存查询向量，避免重复请求。切换算法或调整 Top-K 后，结果会基于缓存自动重算。
🔧 基础调试
这是最"硬核"的面板——直接面向 Embedding API 的原始请求和响应。
典型使用场景：
- 协议对接：刚接入了一个新的 Embedding 模型，想确认 API 是否正常工作
- 维度验证：需要确认模型的实际输出维度是否与文档一致
- 性能测试：想估算单次 Embedding 请求的耗时和 Token 消耗
特殊功能 —— 自定义维度：
对于支持可变维度的模型（如 OpenAI 的 text-embedding-3 系列），你可以在"维度"选择器中指定目标维度（支持 256、512、1024 等常见值）。用更小的维度意味着更低的存储开销和更快的检索速度，但会损失部分精度。
运行结果面板包含：
- 向量预览：自动截取向量的首尾各 5 个数值，让你快速感知数值分布范围
- 统计指标：实际输出维度 + Token 消耗量 + 请求耗时（ms）
- 完整响应 JSON：展示完整的 API 原生响应体，支持高亮和只读浏览
高级用法
增量缓存加速
相似度对比面板内置了一个按模型隔离的增量缓存系统。
当你对同一组文本反复进行对比时（比如切换不同算法对比结果），系统只会对 新增或修改过的文本 发起 API 请求，已缓存的文本直接从内存中读取。这意味着：
- 第二次及以后的操作几乎 零延迟
- 多次切换算法 不产生额外 API 开销
- 换了模型后缓存自动隔离，不会跨模型混用
对比报告导出
在相似度对比的结果面板中，点击复制按钮可以获得格式化的文本报告，包含：
语义相似度排行 (算法: cosine)
基准文本: 计算机科学
#1 [0.8921] 机器学习
#2 [0.8514] 深度学习
#3 [0.8123] 神经网络
...方便你记录到笔记或分享给团队成员。
不同算法的最佳实践
| 算法 | 适用场景 | 注意事项 |
|---|---|---|
| 余弦相似度 | 通用语义对比（最常用） | 忽略向量绝对长度，只关注方向 |
| 点积 | 已归一化向量 | 结果受向量长度影响 |
| 欧氏距离 | 需要关注数值绝对差异 | 已自动转换为相似度分数 |
| 曼哈顿距离 | 高维空间稀疏向量 | 已自动转换为相似度分数 |
常见问题
为什么点击"开始对比"后没有反应？
最常见的原因是没有选择 Embedding 模型。请确保：
- 在设置中配置了至少一个 LLM Profile
- 该 Profile 中包含了支持 Embedding 能力的模型
- 在工具顶部的模型选择器中选中了该模型
不同"相似度算法"得出的排名为什么不一样？
这非常正常。不同的距离/相似度算法从不同角度衡量向量关系：
- 余弦相似度 关注语义方向的一致性
- 欧氏距离 注重绝对位置相近度
- 点积 则考虑了向量模长
切换算法可以帮助你从多个维度理解模型的行为特征。
"检索模拟"中修改了文档，需要重新向量化吗？
是的。修改文档内容后，其向量表示会失效，需要重新执行"一键向量化"来更新索引。修改过的文档左侧的绿色边框会消失，提醒你需要重新向量化。
目前支持哪些 Embedding 模型？
只要在应用的 LLM 配置中添加了支持 Embedding 能力的模型，都可以在 Embedding 测试中使用。具体支持的模型列表取决于你的 LLM Provider 配置。
在何处查看 API Key 和模型配置？
请前往 应用设置 > LLM 配置 中管理你的 Profile 和模型。