在设计智能系统或服务时，开发者可能会关心用户对使用该系统的整体感受或氛围.”氛围测试”可以指一种评估用户在与AI交互过程中感受到的情绪反应、舒适度或满意度的方法。下文介绍一种氛围测试。
1 项目概览：Correlations 是什么？
Correlations 是一个交互式 UI 工具，Jina AI 开源项目 Correlations 用于调试和可视化文本或图像向量之间的相似性关系，特别适合：快速把相关内容两两对照，比单纯数字报告更直观。Correlations 把这种快速、主观“氛围检视”做成了可视化工具，并允许继续深挖定量指标。在大模型时代，这种把“定性直觉”与“定量分析”无缝衔接的工具，会成为 Embedding / RAG / 多模态系统调试的常用武器。
典型使用场景
- 向量模型调试（如文本 embedding 模型）技术博客 vs 论文内容对齐 – 一条明显的对角线 = 两份材料块级对应复用高。
- RAG 引文核查 – 把“生成答案声明”与“检索段落”做二部矩阵，高分块应落在选区内，否则提示幻觉。
- 内容分块策略评估（如 Late Chunking）Late-Chunking 策略验证 – 同一文档不同分块法的自相关热图呈现不同“方格”纹理，可直观看出上下文破碎与否
- 多模态向量（图文检索）对齐分析。跨模态 (图-文) 关联 – 配合 jina-clip-v2，鼠标悬停即显示原图；可检查图片与 alt 文本、商品描述是否匹配。
- Embedding 的氛围测试（vibe-check）——可视化第一眼看相似与否
它的本质是将两个嵌入向量集合之间的**余弦相似度矩阵（Cosine Similarity Matrix）**渲染为一个热图，并提供丰富的交互功能让你“用肉眼判断”相似性结构。测试结果截图如下
1.1 核心原理
你已经有了一份或两份嵌入（embedding）向量文件 JSONL 格式：
{"chunk": "文本块1", "embedding": [0.12, 0.45, ...]}
{"chunk": "文本块2", "embedding": [0.33, 0.66, ...]}
...
这些向量一般由文本或图像编码器（如 BERT、GTE、CLIP）生成，维度通常是 384、768、1024 之类。
我们要做的事情是：
把所有内容块之间的相似度计算出来，并用热图呈现出来。
假设我们有两个 JSONL 文件：
- A.jsonl：原文内容 → 生成了 m 个向量
- B.jsonl：摘要或目标内容 → 生成了 n 个向量
每个向量维度为 d，则可以组成两个矩阵：
符号 | 维度 | 含义 |
A | m × d | 原文块的向量矩阵，每行是一个向量 |
B | n × d | 摘要块的向量矩阵，每行是一个向量 |
如果只有一个文件（自相关热图），那就令 B = A。
余弦相似度的定义
对于两个向量 ，它们的余弦相似度定义为：
也就是：向量点积除以它们的模长乘积，衡量它们的夹角是否接近。
- 越接近 1 → 表示越相似
- 接近 0 → 表示无关
- 接近 -1 → 表示对立
向量矩阵计算过程详解
我们要生成一个 相似度矩阵 S ∈ R^{m×n}，第 i 行第 j 列的值是第 i 个原文向量与第 j 个摘要向量的余弦相似度。
关键公式：
分步解释：
Step 1：矩阵乘法
- 所以结果是
这一步得到所有向量的点积。
Step 2：除以范数乘积（广播）
对每一行 a_i 和每一列 b_j：
- 先计算 A_norms（大小为 m）：每一行向量的 L2 范数
- 再计算 B_norms（大小为 n）：每一列向量的 L2 范数
最后：
得到的矩阵 S：
- 每个格子 S[i][j] 就是第 i 个原文块和第 j 个摘要块的语义相关程度
- 可用热图显示，颜色越深 = 越相似
- 横轴是摘要（query），纵轴是原文（reference）
通过构造两个矩阵（原文向量 A 和摘要向量 B），计算它们所有可能组合的语义相似度（余弦值），形成一个矩阵 S，并将其可视化为热图
2 使用流程详解（两大步骤）
2.1 生成嵌入文件 npm run embed
该步骤是把原始内容（文本或图像）分块后，使用 Jina API 生成向量（embedding），保存为 .jsonl 文件。
命令格式：
npm run embed -- <输入文件路径或URL> [选项]
主要参数说明：
参数 | 含义 | 示例 |
<input> | 本地文本路径 / 网络 URL / 图片文件路径列表 | input.txt, https://xxx.com/doc |
-c, --chunk | 分块策略，默认 newline | punctuation, characters, regex |
-v, --value | 对应的值，如字符数或正则表达式 | --chunk characters --value 500 |
-l, --late-chunking | 启用后，先整段编码再切块，适合上下文语义保持 | --late-chunking |
-t, --task-type | 任务类型，影响 embedding 模型使用的提示语 | retrieval.passage, retrieval.query, text-matching |
-m, --model | 使用的模型，如 jina-embeddings-v3, jina-clip-v2（图像） | 默认 jina-embeddings-v3 |
-o, --output | 输出路径，JSONL 格式 | -o file.jsonl |
示例：
npm run embed -- https://jina.ai/news/... -o v3-blog.jsonl -t retrieval.query
npm run embed -- input.txt --chunk punctuation -o out.jsonl
2.2 可视化相似度热图 npm run corr
读取一个或两个嵌入 .jsonl 文件，计算两组向量之间的余弦相似度矩阵，启动本地服务器呈现可交互热图。
命令格式：
npm run corr -- <file1.jsonl> [file2.jsonl]
参数 | 含义 |
<file1> | 第一个嵌入文件 |
[file2] | 第二个嵌入文件（可选） |
-p, --port | 指定前端可视化端口，默认 3000 |
示例：
npm run corr -- file1.jsonl
npm run corr -- file1.jsonl file2.jsonl
npm run corr -- file1.jsonl --port 8080
3 可视化界面功能详解
访问地址：http://localhost:3000
主视图（热图）
- 每一个格子表示一个内容块之间的余弦相似度值。
- 深色 = 高相似度，浅色 = 低相似度。
- 横轴 = file2 内容块，纵轴 = file1 内容块（如果是自相关，横纵轴一致）。
控制面板（右上角）
- 布局切换：单视图 / 垂直拆分 / 水平拆分（对比两个数据源）
- 相似度阈值过滤：可调整范围（0 ~ 1），只显示高于阈值的格子
- 文本长度过滤：排除过短内容块
- 配色方案切换：支持 RdBu, Viridis, Plasma, Inferno
交互功能
- 悬停查看：鼠标悬停任意格子，显示对应原文块 + 相似度得分
- 拖动选框分析：在热图上框选一片区域，将显示所有块对内容和分数
- “边界详情表”：提供相似度接近阈值的 Top-N 结果，便于人工评审边界样本
4 典型高级用法示例
用例 | 命令示例 |
本地文本自相关分析 | npm run embed -- input.txt -o file.jsonl npm run corr -- file.jsonl |
网页内容对齐分析 | npm run embed -- https://xxx.com -o web.jsonl |
RAG 检索结果 vs 生成答案比对 | npm run embed -- passage.txt -o rag.jsonl -t retrieval.passage npm run embed -- answer.txt -o answer.jsonl |
图像 vs 文本对齐分析 | npm run embed -- all_images.txt --model jina-clip-v2 npm run corr -- images.jsonl text.jsonl |
多模型结果比较 | 准备多个模型输出的 .jsonl 文件，交叉对比可视化 |
## 5 替代 JINA API：用本地 gte-large-zh 生成 JSONL 嵌入向量
5.1 前置准备
pip install sentence-transformers pandas tqdm
Excel → 本地向量 JSONL 的 Python 脚本
假设你有一个 Excel 文件 summary_pairs.xlsx，列名为 "标准答案" 和 "AI原始回答"，你希望分别生成两份 .jsonl 向量文件供 Correlations 使用。
from sentence_transformers import SentenceTransformer
import pandas as pd
import json
from tqdm import tqdm
model = SentenceTransformer('thenlper/gte-large-zh') # 中文优化的 GTE 模型
df = pd.read_excel("summary_pairs.xlsx")
source_jsonl = open("source_embed.jsonl", "w", encoding="utf-8")
summary_jsonl = open("summary_embed.jsonl", "w", encoding="utf-8")
source_texts = df["标准答案"].fillna("").tolist()
summary_texts = df["AI原始回答"].fillna("").tolist()
source_vecs = model.encode(source_texts, convert_to_numpy=True, normalize_embeddings=True, show_progress_bar=True)
summary_vecs = model.encode(summary_texts, convert_to_numpy=True, normalize_embeddings=True, show_progress_bar=True)
for text, emb in zip(source_texts, source_vecs):
source_jsonl.write(json.dumps({
"chunk": text,
"embedding": emb.tolist()
}, ensure_ascii=False) + "\n")
for text, emb in zip(summary_texts, summary_vecs):
summary_jsonl.write(json.dumps({
"chunk": text,
"embedding": emb.tolist()
}, ensure_ascii=False) + "\n")
source_jsonl.close()
summary_jsonl.close()
输出结果：
- source_embed.jsonl：原文块及其向量
- summary_embed.jsonl：摘要块及其向量
5.2 使用 Correlations 可视化本地生成的嵌入
不需要任何 JINA API Key，直接运行：
npm run corr -- source_embed.jsonl summary_embed.jsonl
打开浏览器访问 http://localhost:3000 即可看到原文与摘要之间的相似度热图。
- 每列 = 一个摘要句
- 每行 = 一个原文句
- 格子深色 = 向量余弦相似度高（内容语义相关）
你可以：
- 快速识别不匹配的摘要（全列都浅色）
- 找出摘要重复引用（多列集中在某几行）
6 环境安装
第 1 步：配置 npm 使用代理 + 国内镜像
npm config set proxy http://proxy.com.cn:80
npm config set https-proxy http://proxy.com.cn:80
npm config set registry https://registry.npmmirror.com
npm config set fetch-retry-maxtimeout 60000
npm config set timeout 60000
第 2 步：安装 Node.js 版本管理工具 n
sudo npm install -g n
第 3 步：配置 n 工具使用国内镜像 + 代理
export http_proxy=http://proxy.com.cn:80
export https_proxy=http://proxy.com.cn:80
export N_NODE_MIRROR=https://npmmirror.com/mirrors/node
sudo http_proxy=$http_proxy https_proxy=$https_proxy N_NODE_MIRROR=$N_NODE_MIRROR /usr/local/bin/n lts