Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* EmbeddingClient — OpenAI /v1/embeddings 兼容客户端 (XD Gateway)。
*
* 设计:
* - 零运行依赖, 仅用全局 fetch (Node 18+ / Electron 28+)
* - 同步语义: 调方传 N 条 → 一次 HTTP 请求 (拆批/速率控制由上层 Worker 决定, 不在本层做)
* - 重试: 5xx / 429 / network 走指数退避 (1s / 5s / 15s, 最多 3 次)
* - 缓存: 进程内 LRU, key = sha256(model + '\0' + text); 命中位次回填 embeddings
* - 错误: 统一 EmbeddingError + code, 让 Worker 按 code 决定是否计 attempts
*
* 不做:
* - 拆批 (调方自负 model.maxTokens)
* - 持久化缓存 (Phase 1.1 范围外)
* - 自动 model fallback (consumer 业务决策)
*
* 两条嵌入路径:
* - `embed()` : 一批独立文本 → 一批向量。走 LRU 缓存。
* - `embedDocuments()`: 上下文化(voyage-context-*)索引侧 —— 按文档分组,同文档
* chunk 互为上下文。**不走缓存**:一个 chunk 的向量取决于它所在文档,单 chunk
* 级 key 表达不了这个依赖,缓存了就会在"同一段文字出现在另一个文档里"时给错。
* 两条路径共用同一个 endpoint 与同一套响应解析(见 ContextualizedResponse)。
*/
import { createHash } from 'node:crypto';
import { getEmbeddingModel, isKnownEmbeddingModel, listEmbeddingModels } from './catalog.js';
import { LruCache } from './lruCache.js';
import {
EmbeddingError,
type EmbedDocumentsRequest,
type EmbedDocumentsResponse,
type EmbedRequest,
type EmbedResponse,
type EmbeddingClientOptions,
type EmbeddingInputType,
type EmbeddingLogger,
type EmbeddingModelMeta,
} from './types.js';
/**
* 中立 inputType → 各家 wire 值。null = 该家不支持,不发这个字段。
*
* 值域是**互斥**的(2026-08-04 经 XD 网关实测,见 apps/desktop 的
* ipc/dev/embedding.ts 透传探测):
* - voyage 传大写 → 500 VoyageException;
* - google(经 Vertex)传小写 → 400 Invalid value at 'task_type';
* - openai 两种都回 200 但无任何效果(参数不存在,被静默忽略)。
* 所以这里必须按 provider 翻译,不能原样透传 —— 透传等于让一半模型确定性报错。
*/
const INPUT_TYPE_WIRE: Record<
EmbeddingModelMeta['provider'],
Record<EmbeddingInputType, string> | null
> = {
voyage: { query: 'query', document: 'document' },
google: { query: 'RETRIEVAL_QUERY', document: 'RETRIEVAL_DOCUMENT' },
openai: null,
};
const DEFAULT_CACHE_SIZE = 1000;
// 重试间隔 (ms): 1s / 5s / 15s. 共最多 4 次尝试 (initial + 3 retries)。
const RETRY_DELAYS_MS = [1_000, 5_000, 15_000];
interface OpenAiEmbeddingsResponse {
object: 'list';
data: Array<{ object: 'embedding'; embedding: number[]; index: number }>;
model: string;
usage?: { prompt_tokens?: number; total_tokens?: number };
}
/**
* 网关 /v1/embeddings 的两种响应形态(2026-08-04 自 live gateway LiteLLM 实抓)。
*
* A. 一层 flat —— 普通型号:`data: [{ object:'embedding', index, embedding }]`
* B. 两层嵌套 —— voyage-context-*:
* `data: [{ object:'list', index, data: [{ object:'embedding', index, embedding }] }]`
* 外层一项 = 一个文档,内层 = 该文档的 per-chunk 向量。
*
* **形态由型号决定,不由请求决定**:voyage-context-* 的查询侧请求虽然发的是一维
* `input`,回来的**仍然是**两层(每个 input 成为一个单 chunk 文档)。所以扁平路径
* (`embed()`)也必须能吃嵌套响应 —— 只按 `data[].embedding` 解析会对这些型号
* 直接失败。两条路径因此共用 `parseGroupedEmbeddings`。
*/
interface ContextualizedResponse {
data: Array<
| { object?: 'embedding'; embedding: number[]; index?: number }
| { object?: 'list'; data: Array<{ embedding: number[]; index?: number }>; index?: number }
>;
model: string;
usage?: { prompt_tokens?: number; total_tokens?: number };
}
/**
* 按响应项自报的 `index` 把它们放回确定的位次;`index` 缺省时退回数组序。
*
* 为什么不是"排个序就完事"(PR #1707 review):排序只保证顺序单调,不保证位次是**一个
* 双射**。上游回重复 index(如请求 2 项、响应 index 为 0/1/1)时,排序后条数可能刚好
* 对得上,于是所有条数校验都通过,而某一项的向量被另一项静默顶掉 —— 交付出去的是
* 错误位置的向量,不报任何错。越界 index 同理:多出来的项如果不导致缺位,就完全不会
* 被发现。所以这里要求 **项数相等 + 无重复 + 无越界**,三条齐了位次才必然填满。
*
* `what` 只用于报错定位(document / chunk / embedding)。
*/
function orderedByIndex<T>(
items: readonly T[],
indexOf: (item: T, arrayOrder: number) => number,
expected: number,
what: string,
): T[] {
if (items.length !== expected) {
throw new EmbeddingError(
`contextualized response: got ${items.length} ${what} entries, expected ${expected}`,
'SERVER_ERROR',
);
}
const slots = new Array<T | undefined>(expected);
items.forEach((item, arrayOrder) => {
const idx = indexOf(item, arrayOrder);
if (!Number.isInteger(idx) || idx < 0 || idx >= expected) {
throw new EmbeddingError(
`contextualized response: ${what} index ${String(idx)} out of range (expected 0..${expected - 1})`,
'SERVER_ERROR',
);
}
if (slots[idx] !== undefined) {
throw new EmbeddingError(
`contextualized response: duplicate ${what} index ${idx}`,
'SERVER_ERROR',
);
}
slots[idx] = item;
});
// 项数相等 + 无重复 + 无越界 ⇒ 每个位次都被填过,无需再判空。
return slots as T[];
}
/**
* 一条向量必须是"元素全为有限数字的数组"。
*
* 为什么不能只看长度(PR #1707 review 第十一轮):200 响应里的 `embedding` 完全可能是
* `["0.1", null, {}]` 甚至一个字符串 —— 后者连 `.length` 都有,下游的维度校验读到的是
* 字符数,`dim` 看着还很合理。整批就这么被当成合法向量交付、入缓存,插件把它写进索引,
* 之后每次检索都是噪声,而哪一步都没报错。
*
* `NaN` / `±Infinity` 同样拒:它们会让余弦相似度整列变成 NaN,坏得更彻底也更难查。
*/
function assertNumericVector(value: unknown, what: string): number[] {
if (!Array.isArray(value)) {
throw new EmbeddingError(
`contextualized response: ${what} is not an array (got ${typeof value})`,
'SERVER_ERROR',
);
}
for (let i = 0; i < value.length; i++) {
const coord: unknown = value[i];
if (typeof coord !== 'number' || !Number.isFinite(coord)) {
// 坏值本身进不去消息(可能是个巨大对象),只报类型 / 数值形态。
const shown = typeof coord === 'number' ? String(coord) : typeof coord;
throw new EmbeddingError(
`contextualized response: ${what} coordinate ${i} is not a finite number (got ${shown})`,
'SERVER_ERROR',
);
}
}
return value as number[];
}
/**
* 把响应解析成按文档分组的向量。两种形态都吃(见 ContextualizedResponse 注释),
* 形状不认识时抛 SERVER_ERROR 而不是给出半个结果。
*
* 逐坐标的数字校验也在这里(见 assertNumericVector):这是两条路径(扁平 / 上下文化)
* 唯一共同的入口,放在这里 = 没有一条非数字向量能溜到缓存或交付面。
*
* `groupSizes` 是**期望**的分组:扁平路径传全 1(每个 input 一个单 chunk 文档),
* 上下文化索引侧传各文档真实 chunk 数。它同时充当条数校验 —— 上游少给 / 多给、
* 或 index 重复 / 越界,都在这里失败,不会让调方拿到错位的向量。
*/
function parseGroupedEmbeddings(
body: ContextualizedResponse,
groupSizes: readonly number[],
): number[][][] {
const items = body.data ?? [];
const nested = items.length > 0 && Array.isArray((items[0] as { data?: unknown }).data);
if (nested) {
// 嵌套形态:一项一个文档。外层与内层都要求 index 构成双射(见 orderedByIndex)。
const docs = orderedByIndex(
items as Array<{ index?: number; data: Array<{ embedding: number[]; index?: number }> }>,
(item, arrayOrder) => item.index ?? arrayOrder,
groupSizes.length,
'document',
);
return docs.map((doc, docIndex) => {
const chunks = orderedByIndex(
doc.data ?? [],
(entry, arrayOrder) => entry.index ?? arrayOrder,
groupSizes[docIndex],
`document ${docIndex} chunk`,
);
return chunks.map((entry, chunkIndex) =>
assertNumericVector(entry.embedding, `document ${docIndex} chunk ${chunkIndex} embedding`),
);
});
}
// 扁平形态:所有 chunk 按全局顺序摊平,按 groupSizes 重新切回文档。
// 形状判定要走在位次解析之前 —— 条数刚好对上的坏形态应当报"形状不认识",
// 而不是报一个会把人带偏的条数/位次错误。
const raw = items as Array<{ embedding?: number[]; index?: number }>;
if (raw.some((item) => !Array.isArray(item.embedding))) {
throw new EmbeddingError(
'contextualized response: unrecognized data shape (neither flat embeddings nor per-document groups)',
'SERVER_ERROR',
);
}
const total = groupSizes.reduce((sum, n) => sum + n, 0);
const flat = orderedByIndex(
raw,
(item, arrayOrder) => item.index ?? arrayOrder,
total,
'embedding',
).map((item, i) => assertNumericVector(item.embedding, `embedding ${i}`));
const out: number[][][] = [];
let cursor = 0;
for (const size of groupSizes) {
out.push(flat.slice(cursor, cursor + size) as number[][]);
cursor += size;
}
return out;
}
interface OpenAiErrorResponse {
error?: { message?: string; type?: string; code?: string };
}
/**
* 一批向量里第一个与首条长度不同的下标; 全部等长(或空批)时返 null。
* 用于"缓存命中项 + 新取回项"合并后的自洽复查, 那里没有期望维度可比, 只能看内部一致性。
*/
function mixedLengthAt(vectors: readonly number[][]): number | null {
const first = vectors[0]?.length;
if (first === undefined) return null;
for (let i = 1; i < vectors.length; i++) {
if (vectors[i]?.length !== first) return i;
}
return null;
}
/** 报错里的位置描述; 扁平路径每组恒 1 条, 组下标即文本下标。 */
function positionLabel(mode: 'flat' | 'grouped', group: number, chunk: number): string {
return mode === 'flat' ? `index ${group}` : `group ${group} index ${chunk}`;
}
/**
* 校验**批内每一条**向量的长度都一致、非空, 且(显式请求了维度时)等于请求值。
*
* 两件事分开说:
*
* 1. 只看首条不够(PR #1707 review 第四轮):首条对、后面某条错时检查会通过, 整批被
* 缓存并交付, 上层(cindySlot)又按首条填 `dim` —— 调方拿到一批"声称同维度"其实
* 不等长的向量, 写进索引后相似度失去意义, 而且哪一步都没有报错。
*
* 2. **没显式传 dimensions 时也必须校验**(同 review 第五轮):那是文档示例和绝大多数
* 调用走的路径, 之前直接 return 等于整条默认路径零校验。这里的判据是"全批与首条
* 一致"而不是"等于 catalog 的 `dim`":catalog 的 `dim` 记的是**上游当前的默认值**,
* 上游改默认时拿它硬判会把本来正常的响应全判失败;而"批内不等长"无论默认值是多少
* 都一定是坏数据。
*
* 3. **零长度一律非法**(同 review 第十轮):缺省维度那条路径上, 上游以 200 回一批空
* 数组时"全批与首条一致"是成立的(expected 取到 0), 整批会通过校验、进缓存、
* 并让 slot 回一个 `dim: 0` 给插件 —— 插件把空向量写进索引, 之后的缓存命中继续
* "成功"。默认维度允许变, 但合法 embedding 的长度必须为正, 这条与维度无关。
*
* 4. **"是谁错了"要看整批, 不能看到第一条不一致就下结论**(同 review 第十三轮):
* 显式传了 dimensions 时有两种坏法, 结论相反 ——
* - 整批**一致地**不等于请求值 = 这个型号根本不吃这个维度(静默回了它的默认),
* 调方改参数才有救 → `INVALID_MODEL`(slot 译成 `INVALID_PARAMS`);
* - 批内**自相矛盾**(有的等于请求值、有的不等) = 型号明显吃得下这个维度,
* 是这一批响应畸形, 调方的请求完全合法 → `SERVER_ERROR`(slot 译成 `INTERNAL`)。
* 第二种若也报 INVALID_MODEL, 手册会让插件"改一个没问题的请求、原样重试永远失败",
* 于是它可能永久降到另一个维度或型号 —— 按一个假诊断重建索引。
* 区分不了的原因是时机: 扫到第一条不一致时还不知道后面有没有等于请求值的, 所以
* 先收齐全批长度再分类。
*
* 上游对不支持的维度行为不统一(可能 400, 也可能静默回默认长度), 这里是最后一道
* 能看见长度的地方; 也是**每条向量进缓存前的唯一关口**(见 embed() 的调用位置)。
*
* `mode` 只影响报错里的位置描述:扁平路径每组恒为 1 条(组下标 = 文本下标),报
* "group 3 index 0" 只会让调方困惑。
*/
function assertBatchDimensions(
grouped: readonly number[][][],
model: string,
dimensions: number | undefined,
mode: 'flat' | 'grouped',
): void {
// 先收齐全批的长度与位置。空向量在这一趟里就地拒掉(它与"请求了什么维度"无关),
// 长度的**归属判定**留到收齐之后 —— 见文档注释第 4 条。
const seen: Array<{ length: number; at: string }> = [];
for (let d = 0; d < grouped.length; d++) {
const group = grouped[d];
for (let c = 0; c < group.length; c++) {
const got = group[c]?.length;
if (got === undefined) continue;
if (got === 0) {
throw new EmbeddingError(
`model '${model}' returned an empty embedding at ${positionLabel(mode, d, c)}`,
'SERVER_ERROR',
);
}
seen.push({ length: got, at: positionLabel(mode, d, c) });
}
}
if (seen.length === 0) return;
// 批内自洽:基准取首条 —— 校验的是"整批一致",不是"符合某个记在客户端里的常量"。
const baseline = seen[0].length;
const ragged = seen.find((v) => v.length !== baseline);
if (ragged) {
// 位置信息带上:一批 32 条里第 17 条错,没有下标就只能靠猜。
// 不等长**一律**归主机:显式传了 dimensions 时它意味着"型号吃得下这个维度,只是
// 这批响应畸形"(否则不会有任何一条对上),调方的请求本身没问题。
const suffix = dimensions === undefined ? '' : ` (requested dimensions=${dimensions})`;
throw new EmbeddingError(
`model '${model}' returned mixed vector lengths (${baseline} then ${ragged.length}) at ${ragged.at}${suffix}`,
'SERVER_ERROR',
);
}
// 走到这里全批等长。只有"一致地不等于请求值"才是参数问题 —— 型号静默回了它自己的
// 默认维度,调方改参数(或换型号)才有救。
if (dimensions !== undefined && baseline !== dimensions) {
throw new EmbeddingError(
`requested dimensions=${dimensions} but model '${model}' returned ${baseline} at ${seen[0].at}`,
'INVALID_MODEL',
);
}
}
/**
* 缓存项 = 向量 + **产出它的上游实际型号**。
*
* 为什么必须连型号一起存(PR #1707 review 第十轮):请求里给的是别名, 上游返的
* `model` 才是实际型号(可能带版本号, 也可能在服务端换后端时变)。只存向量的话:
* - 全命中时只能回别名, 同一段文本第二次调用的 `model` 元数据凭空变了一次,
* 插件会据此误判索引需要重建;
* - 别名换后端而维度恰好相同时, 旧缓存向量与新取回向量会被混在一批里、统一
* 标成新型号 —— 两个模型的向量不可比, 而形状完全正常, 没有任何报错。
*/
interface CachedVector {
readonly vector: number[];
/** 写入这条缓存时上游回的 `model`(缺省则为请求别名)。 */
readonly model: string;
}
export class EmbeddingClient {
private readonly resolveBaseUrl: () => string;
private readonly getApiKey: () => string | undefined | null;
private readonly fetchImpl: typeof fetch;
private readonly cache: LruCache<string, CachedVector>;
private readonly log: EmbeddingLogger;
constructor(opts: EmbeddingClientOptions) {
// baseUrl 支持函数形态:宿主的网关 endpoint 可能在运行期变化(如登录后由
// 服务端下发),每次请求现取,避免构造期快照钉死旧地址。
const normalize = (raw: string): string => {
let baseUrl = raw;
while (baseUrl.endsWith('/')) baseUrl = baseUrl.slice(0, -1);
return baseUrl;
};
const rawBaseUrl = opts.baseUrl;
this.resolveBaseUrl =
typeof rawBaseUrl === 'function' ? () => normalize(rawBaseUrl()) : () => normalize(rawBaseUrl);
this.getApiKey = opts.getApiKey;
this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
this.cache = new LruCache<string, CachedVector>(opts.cacheSize ?? DEFAULT_CACHE_SIZE);
this.log = opts.logger ?? {};
if (typeof this.fetchImpl !== 'function') {
throw new Error('EmbeddingClient: global fetch not available; pass fetchImpl');
}
}
/** 列出 catalog 中所有可用模型, 调方做 UI 选择 / 校验。 */
listModels(): EmbeddingModelMeta[] {
return listEmbeddingModels();
}
/**
* 嵌入一批文本。返 embeddings 与 texts 一一对应; 缓存命中位次直接回填。
* texts 为空数组 → 直接返空结果, 不打网络。
*/
async embed(req: EmbedRequest): Promise<EmbedResponse> {
if (!isKnownEmbeddingModel(req.model)) {
throw new EmbeddingError(
`unknown embedding model '${req.model}'`,
'INVALID_MODEL',
);
}
if (req.texts.length === 0) {
return { embeddings: [], modelUsed: req.model, tokensUsed: 0, cacheHits: 0 };
}
// 本次调用的起点 —— 只用于下面"清缓存重取"那条路径:重取必须吃掉**同一份**预算的
// 剩余量,不能重新计时(见那里的注释)。
const startedAt = Date.now();
// 1. 查缓存, 拆出 miss index
const result: number[][] = new Array(req.texts.length);
const missIdx: number[] = [];
const missTexts: string[] = [];
let cacheHits = 0;
// inputType / dimensions 必须计入 key:同一段文本在 query 档与 document 档下是
// 两个不同的向量(上游加了不同前缀), 维度不同更是长度都不一样。漏计 = 后到的
// 请求静默拿到前一档的向量, 而且因为形状看起来正常, 排查时毫无线索。
const variant = cacheVariant(req.inputType, req.dimensions);
// 命中项各自来自哪个上游型号 —— 交付前要求整批同源(见下面两处判据)。
const hitModels = new Set<string>();
for (let i = 0; i < req.texts.length; i++) {
const key = cacheKey(req.model, req.texts[i], variant);
const cached = this.cache.get(key);
if (cached) {
result[i] = cached.vector;
hitModels.add(cached.model);
cacheHits++;
} else {
missIdx.push(i);
missTexts.push(req.texts[i]);
}
}
// 全命中 — 不打网络。但仍要复查批内自洽:缓存里完全可能同时存着两种维度的向量
// (PR #1707 review 第九轮)。到达路径不需要什么巧合:文本 A 在旧默认维度下入缓存,
// 上游改默认,随后某次只含文本 B 的请求把 B 以新维度入缓存 —— 那一次零命中、新批
// 内部自洽,前面那道复查进不来。此后任何同时要 A 和 B 的请求都是全命中,直接从这里
// 返回一批混合长度的向量。
if (missTexts.length === 0) {
if (mixedLengthAt(result) !== null) {
return this.refetchAfterCacheReset(req, startedAt, 'all-cache-hit batch mixes dimensions');
}
// 命中项跨了两个上游型号(别名在中途被换了后端, 且维度恰好相同)—— 两个模型的
// 向量不可比, 清缓存重取一批同源的。
if (hitModels.size > 1) {
return this.refetchAfterCacheReset(
req,
startedAt,
`all-cache-hit batch spans models ${[...hitModels].join(' / ')}`,
);
}
return {
embeddings: result,
// 回**缓存里记的实际型号**而不是请求别名:同一段文本第二次调用时 model 元数据
// 不能凭空变一次, 否则插件会误判索引要重建 (review 第十轮)。
modelUsed: hitModels.values().next().value ?? req.model,
tokensUsed: 0,
cacheHits,
};
}
// 2. 调 XD Gateway
const apiKey = this.getApiKey();
if (!apiKey) {
throw new EmbeddingError(
'no API key available (user not logged in or safeStorage failure)',
'AUTH_FAILED',
);
}
const apiResponse = await this.callWithRetry(apiKey, req.model, missTexts, req);
// 3. 写回结果 + 缓存
//
// 一维 input 也可能拿到两层嵌套响应 —— voyage-context-* 的形态由**型号**决定,
// 与请求是几维无关(每个 input 成为一个单 chunk 文档)。所以统一走
// parseGroupedEmbeddings:期望分组为"N 个文档各 1 chunk",再摊平回一维。
// 条数校验也在那里做(少给/多给都失败,不会错位交付)。
const grouped = parseGroupedEmbeddings(
apiResponse as unknown as ContextualizedResponse,
missTexts.map(() => 1),
);
// 维度自检:显式请求了维度就必须兑现。上游对"不支持的维度"行为不统一(可能
// 400, 也可能静默回默认长度), 静默那条最危险 —— 调方按请求值建索引 / 预分配,
// 拿到的却是另一个长度, 而报错点会漂到很远的地方。
//
// **必须在写缓存之前判**(PR #1707 review):先写后判会让本次抛错、缓存里却留下
// 那批错长度的向量 —— 下一次同参请求全命中缓存直接 return, 绕过这里的自检把
// 非法向量当成功交付出去。判在前面 = 非法响应一条都不入缓存。
assertBatchDimensions(grouped, req.model, req.dimensions, 'flat');
// 本批新向量的实际型号:上游回的 `model` 优先, 缺省退回请求别名。缓存项跟着记它。
const freshModel = apiResponse.model || req.model;
for (let j = 0; j < missTexts.length; j++) {
const vec = grouped[j]?.[0];
if (!vec) {
throw new EmbeddingError(
`XD Gateway response missing embedding for input index ${j}`,
'SERVER_ERROR',
);
}
const targetIdx = missIdx[j];
result[targetIdx] = vec;
this.cache.set(cacheKey(req.model, missTexts[j], variant), { vector: vec, model: freshModel });
}
// 组装后再校验一次"整批自洽" —— 上面那次只看了**新取回的**那部分。
//
// 漏掉的场景(PR #1707 review 第七轮):没显式传 dimensions、本批既有缓存命中又有
// 未命中、且上游在本进程存活期间调了该型号的默认维度。命中项是旧维度(如 1024)、
// 新取回的是新维度(如 3072),各自内部都自洽,于是前一道检查放行 —— 交付出去的是
// 一批混合长度的向量,cindySlot 还按首条填 dim。
//
// 不能靠"对着 catalog 的 dim 判"来发现它:那个常量记的是上游当前默认值,上游改了
// 之后它本身就是过期的(本文件的用例明确允许默认维度偏离 catalog)。唯一可靠的信号
// 就是"同一批里长度不一致"。
//
// 处置:清空缓存后整批重取一次。清得比必要范围大(其它型号的条目也没了)是有意的 ——
// 默认维度一变,该型号所有缓存向量都已过期,而缓存只是内存里的性能优化,重取的代价
// 远小于交付错数据。递归至多一次:清空后 cacheHits 必为 0,这个分支进不来。
if (cacheHits > 0 && mixedLengthAt(result) !== null) {
return this.refetchAfterCacheReset(req, startedAt, 'cache hits mixed with fresh results');
}
// 同理的另一半:命中项与新取回项来自**不同型号**。别名换了后端而维度恰好相同时,
// 长度检查一律放行, 而下面会把整批统一标成 freshModel —— 一批里混着两个模型的
// 向量、却声称同一个型号, 是"不报错只是悄悄错"里最难查的一种 (review 第十轮)。
if (cacheHits > 0 && [...hitModels].some((m) => m !== freshModel)) {
return this.refetchAfterCacheReset(
req,
startedAt,
`cached model ${[...hitModels].join(' / ')} != upstream model ${freshModel}`,
);
}
return {
embeddings: result,
modelUsed: freshModel,
tokensUsed: apiResponse.usage?.prompt_tokens ?? apiResponse.usage?.total_tokens ?? 0,
cacheHits,
};
}
/**
* 发现缓存与本批**不同源**时(维度不一致 / 上游型号不一致):清空缓存,整批重取一次。
*
* 两种不同源用同一个处置,因为它们坏的是同一件事:一批向量必须来自同一个模型的
* 同一个维度档,否则相似度比较无意义 —— 而两种情况下形状都可能完全正常。
*
* 清得比必要范围大(其它型号的条目也没了)是有意的 —— 默认维度或后端一变,该型号所有
* 缓存向量都已过期,而缓存只是内存里的性能优化,重取的代价远小于交付错数据。
*
* 重取吃**同一份**预算的剩余量:`timeoutMs` 是时长而不是绝对截止点,原样递下去等于
* 重新计时 —— 第一次已经花掉 55 秒时重取还能再等 60 秒,插件那一次 await 最长接近
* 120 秒,在途额度也一直占着,与手册承诺的"单次请求 60 秒"直接矛盾。
*
* 递归至多一次:清空后本批全是 miss,四处调用点都以"有命中"为前提(全命中分支进不来,
* 混合分支的 `cacheHits > 0` 也不成立)。
*/
private async refetchAfterCacheReset(
req: EmbedRequest,
startedAt: number,
why: string,
): Promise<EmbedResponse> {
this.log.warn?.(
`[embedding-client] inconsistent batch (${why}) for '${req.model}'; upstream default dimension or backend model likely changed — clearing cache and refetching`,
);
this.cache.clear();
let remaining: number | undefined;
if (req.timeoutMs !== undefined) {
remaining = req.timeoutMs - (Date.now() - startedAt);
if (remaining <= 0) {
throw new EmbeddingError(
`embed: timed out after ${req.timeoutMs}ms (budget exhausted before cache-reset refetch)`,
'TIMEOUT',
);
}
}
return this.embed({
...req,
...(remaining !== undefined ? { timeoutMs: remaining } : {}),
});
}
/**
* 上下文化嵌入 (voyage-context-* 索引侧):按文档分组嵌入,同文档 chunk 互为上下文。
*
* wire 形态与 `embed()` 同一个端点,差别只在 `input` 是二维数组。
*
* **不走缓存**:一个 chunk 的向量取决于它所在文档,单 chunk 级 key 无法表达这个
* 依赖 —— 缓存了就会在"同一段文字出现在另一个文档里"时给出错误的向量。
*/
async embedDocuments(req: EmbedDocumentsRequest): Promise<EmbedDocumentsResponse> {
if (!isKnownEmbeddingModel(req.model)) {
throw new EmbeddingError(`unknown embedding model '${req.model}'`, 'INVALID_MODEL');
}
if (req.documents.length === 0) {
return { embeddings: [], modelUsed: req.model, tokensUsed: 0 };
}
if (req.documents.some((doc) => doc.length === 0)) {
throw new EmbeddingError('documents 不能包含空的 chunk 序列', 'INVALID_MODEL');
}
const apiKey = this.getApiKey();
if (!apiKey) {
throw new EmbeddingError(
'no API key available (user not logged in or safeStorage failure)',
'AUTH_FAILED',
);
}
const groupSizes = req.documents.map((doc) => doc.length);
const body = await this.callWithRetry(apiKey, req.model, req.documents, req);
const embeddings = parseGroupedEmbeddings(
body as unknown as ContextualizedResponse,
groupSizes,
);
assertBatchDimensions(embeddings, req.model, req.dimensions, 'grouped');
return {
embeddings,
modelUsed: body.model || req.model,
tokensUsed: body.usage?.prompt_tokens ?? body.usage?.total_tokens ?? 0,
};
}
/**
* 带重试的 POST /v1/embeddings。重试条件:
* - 5xx / 429 / NETWORK_ERROR → 退避后重试 (最多 RETRY_DELAYS_MS.length 次)
* - 401/403 (AUTH_FAILED) / 400 (INVALID_MODEL) / TIMEOUT → 立即抛
*
* `opts.timeoutMs` 是**整条链**(含所有重试与退避睡眠)的预算, 不是单次 HTTP 的:
* 每次尝试只拿剩余额度, 退避前先看剩余额度够不够, 不够就直接抛 TIMEOUT 而不是
* 白睡一觉。否则 n 次重试会把调方看到的最坏等待放大成 n 倍预算。
*/
private async callWithRetry(
apiKey: string,
model: string,
// string[][] = 上下文化的按文档分组输入(见 embedDocuments);wire 上原样发。
inputs: string[] | string[][],
opts: Pick<EmbedRequest, 'inputType' | 'dimensions' | 'timeoutMs'>,
): Promise<OpenAiEmbeddingsResponse> {
let attempt = 0;
// initial + retries
const maxAttempts = RETRY_DELAYS_MS.length + 1;
let lastErr: EmbeddingError | null = null;
const deadline = opts.timeoutMs !== undefined ? Date.now() + opts.timeoutMs : null;
while (attempt < maxAttempts) {
try {
let remaining: number | undefined;
if (deadline !== null) {
remaining = deadline - Date.now();
if (remaining <= 0) {
throw new EmbeddingError(
`embed: timed out after ${opts.timeoutMs}ms (budget exhausted before attempt ${attempt + 1})`,
'TIMEOUT',
);
}
}
return await this.callOnce(apiKey, model, inputs, opts, remaining);
} catch (err) {
if (!(err instanceof EmbeddingError)) {
// 防御性: 任何非 EmbeddingError 都视作 SERVER_ERROR 走重试
lastErr = new EmbeddingError(
err instanceof Error ? err.message : String(err),
'SERVER_ERROR',
);
} else {
lastErr = err;
}
const retriable =
lastErr.code === 'NETWORK_ERROR' ||
lastErr.code === 'RATE_LIMITED' ||
lastErr.code === 'SERVER_ERROR';
if (!retriable || attempt >= maxAttempts - 1) {
throw lastErr;
}
const delay = RETRY_DELAYS_MS[attempt];
// 退避前先看预算:睡完必然过期就别睡了,把原始失败原因换成 TIMEOUT 抛出去
// (调方等的是"最多 timeoutMs",不是"最多 timeoutMs + 所有退避时间")。
if (deadline !== null && Date.now() + delay >= deadline) {
throw new EmbeddingError(
`embed: timed out after ${opts.timeoutMs}ms (last failure: ${lastErr.code})`,
'TIMEOUT',
);
}
this.log.warn?.(
`[embedding-client] attempt ${attempt + 1}/${maxAttempts} failed (${lastErr.code}); retry in ${delay}ms`,
);
await sleep(delay);
attempt++;
}
}
// unreachable; throw 早已发生
throw lastErr ?? new EmbeddingError('embed: exhausted retries', 'SERVER_ERROR');
}
/**
* 单次 HTTP 调用, 不重试。
* fetch 抛错 → NETWORK_ERROR; 非 2xx → 按 status 映射 code。
*
* `budgetMs` = 本次尝试可用的剩余时间(由 callWithRetry 从整体预算里切出来)。
* 用自建 AbortController 而不是 `AbortSignal.timeout()`:定时器要能在正常返回后
* 立刻 clear 掉, 不让它空转到超时点(每次调用留一个活定时器会拖住事件循环退出)。
* 计时覆盖到读完 body 为止 —— 响应头很快、body 迟迟不来也算超时。
*/
private async callOnce(
apiKey: string,
model: string,
inputs: string[] | string[][],
opts: Pick<EmbedRequest, 'inputType' | 'dimensions'>,
budgetMs?: number,
): Promise<OpenAiEmbeddingsResponse> {
const url = `${this.resolveBaseUrl()}/v1/embeddings`;
// inputType 按 provider 翻成该家的 wire 值(不支持的家不发这个字段);
// dimensions 统一用 OpenAI 的名字 —— 三家经网关都认它, Voyage 自己的
// output_dimension 只对 voyage 生效。
const provider = getEmbeddingModel(model)?.provider;
const wireInputType =
opts.inputType && provider ? INPUT_TYPE_WIRE[provider]?.[opts.inputType] : undefined;
let controller: AbortController | null = null;
let timer: ReturnType<typeof setTimeout> | null = null;
if (budgetMs !== undefined) {
const c = new AbortController();
controller = c;
timer = setTimeout(() => c.abort(), Math.max(1, budgetMs));
}
// abort 之后 fetch 抛的是 AbortError,与真正的网络故障混在一起 —— 但两者的
// 重试语义相反(网络错该重试、超时不该),所以靠 signal.aborted 而不是错误
// 消息来区分。
//
// 前提:fetchImpl 必须尊重 AbortSignal(真 fetch / undici 的契约)。无视
// signal 的替身若最终正常返回,这里不会把它判成超时 —— 预算只能约束"愿意被
// 中断"的实现,注入自定义 fetchImpl 时需自行保证这一点。
const timedOut = (): boolean => controller?.signal.aborted === true;
try {
let res: Response;
try {
res = await this.fetchImpl(url, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model,
input: inputs,
...(wireInputType ? { input_type: wireInputType } : {}),
...(opts.dimensions !== undefined ? { dimensions: opts.dimensions } : {}),
}),
...(controller !== null ? { signal: controller.signal } : {}),
});
} catch (err) {
if (timedOut()) {
throw new EmbeddingError(`request aborted after ${budgetMs}ms budget`, 'TIMEOUT');
}
// DNS / socket reset 走这里
throw new EmbeddingError(
`network error: ${err instanceof Error ? err.message : String(err)}`,
'NETWORK_ERROR',
);
}
if (!res.ok) {
// 读错误响应体时也可能撞上预算(网关先回了 400 的头,body 却挂住或断流)。
// 这里若把 AbortError 一并吞成空串,下面就会按 HTTP 状态抛 INVALID_MODEL /
// AUTH_FAILED,而外层看到的是 EmbeddingError 也不会再改判 —— 一次实打实
// 耗尽预算的请求就被报成"你该改参数",与结构化错误契约矛盾
// (PR #1707 review)。所以吞之前先看 signal。
const text = await res.text().catch(() => {
if (timedOut()) {
throw new EmbeddingError(`request aborted after ${budgetMs}ms budget`, 'TIMEOUT');
}
return '';
});
let parsedMsg = '';
try {
const parsed = JSON.parse(text) as OpenAiErrorResponse;
parsedMsg = parsed.error?.message ?? '';
} catch {
/* not JSON */
}
const code = mapStatusToCode(res.status);
throw new EmbeddingError(
`XD Gateway /v1/embeddings ${res.status}: ${parsedMsg || text || res.statusText}`,
code,
res.status,
text,
);
}
// body 读到一半被 abort → json() 抛错, 由下面的 catch 归成 TIMEOUT。
// 抢在定时器前读完就照常返回:手里已经是一份合法响应, 不为了"时间刚好到了"
// 把它丢掉再让调方失败。
return (await res.json()) as OpenAiEmbeddingsResponse;
} catch (err) {
// json() / text() 在 abort 后抛的也要归到 TIMEOUT,别伪装成解析失败。
if (timedOut() && !(err instanceof EmbeddingError)) {
throw new EmbeddingError(`request aborted after ${budgetMs}ms budget`, 'TIMEOUT');
}
throw err;
} finally {
if (timer !== null) clearTimeout(timer);
}
}
}
function mapStatusToCode(status: number): EmbeddingError['code'] {
if (status === 401 || status === 403) return 'AUTH_FAILED';
if (status === 400 || status === 404 || status === 422) return 'INVALID_MODEL';
if (status === 429) return 'RATE_LIMITED';
if (status >= 500) return 'SERVER_ERROR';
// 其它 4xx 视作 INVALID 不重试
return 'INVALID_MODEL';
}
/**
* 请求变体标识 —— 同一 (model, text) 在不同 inputType / dimensions 下是不同的向量,
* 必须进 cache key。空串 = 两者都缺省(与加入本参数之前的 key 语义一致)。
*/
function cacheVariant(inputType: string | undefined, dimensions: number | undefined): string {
if (inputType === undefined && dimensions === undefined) return '';
return `${inputType ?? ''}:${dimensions ?? ''}`;
}
function cacheKey(model: string, text: string, variant: string): string {
// sha256(model + '\0' + variant + '\0' + text); 用 NUL 分隔避免
// 'a' + 'bc' / 'ab' + 'c' 碰撞
const h = createHash('sha256');
h.update(model);
h.update('\x00');
h.update(variant);
h.update('\x00');
h.update(text);
return h.digest('hex');
}
function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
// 模型相关的小工具直接 re-export, 方便 consumer 共用同一份 catalog 查询。
export { getEmbeddingModel } from './catalog.js';