文本嵌入

文本嵌入服务将文本转换为向量，用于语义搜索、聚类和记忆检索。选择嵌入提供方后，可通过 ctx.embeddings 使用。

使用服务

import type {Context} from '@deepseek-ai/cordis'
import type {} from '@dsh-ai-providers/core'

export const inject = ['embeddings']

export async function index(ctx: Context, texts: string[]) {
  const result = await ctx.embeddings.embed(texts, {
    inputType: 'document',
    priority: 'background',
  })
  return result.vectors
}

embed() 按输入顺序返回向量、实际响应的模型、向量维度，以及提供方报告的 token 用量。本项目维护的 OpenAI 兼容服务会拒绝空字符串。embedOne() 用于处理单个字符串。

如果提供方区分两类输入，搜索问题使用 inputType: 'query'，被索引内容使用 inputType: 'document'。OpenAI 嵌入 API 没有对应字段，因此 OpenAI 兼容传输层不会发送它；Jina 和 Cohere 提供方都会把它作为模型自身的任务类型发送（retrieval.query 或 search_query，以及对应的文档类型），Ollama 没有对应字段，会忽略它；面向指令式嵌入模型的提供方可以把它转换为模型所需的前缀或字段。不同模型或维度的向量不得比较。@dsh-ai-providers/core 的 cosineSimilarity() 会在比较前验证维度。

预取与分批

prefetch(texts, options) 在后台准备结果，不返回 Promise。所选服务可将其与随后相同的 embed() 调用去重，并在配置的保留期内复用结果。

OpenAI 兼容提供方会按配置的批大小拆分大型输入数组；返回顺序仍与原始输入一致。

OpenAI 兼容选项

选项	含义
dimensions	支持缩短向量的模型所使用的目标维度
user	发送给 API 的可选最终用户标识

该提供方调用 POST /embeddings。

索引一致性

请将返回的 model 与 dimensions 和索引或集合一起保存。如果任一值改变，应在搜索前重建受影响的向量。连接可以在不改变使用方 API 的情况下切换所选模型，但这并不会让新旧模型产生的向量彼此兼容。

适合时应批量提交相关文档。服务会保持顺序，因此调用方可以将 vectors[n] 与 texts[n] 对应；不要从向量内容推断身份。交互式搜索应以前台优先级嵌入问题，大批量索引则使用后台优先级，让并发门控为响应性预留容量。

失败与取消

空输入数组会直接返回空向量列表，不会联系提供方。非空请求中只要包含空字符串，就会产生 invalid-input。提供方无法生成所需维度时为 unsupported；认证、配额和未知模型响应为 rejected。索引任务和用户搜索都应传入所属生命周期的 AbortSignal，使排队工作和活动 HTTP 请求能在所有者消失时停止。

prefetch() 有意采用即发即弃模式：它不返回结果，也不会向调用方抛出错误。应用状态依赖完成或失败时，请始终使用 embed()。