plugin-embedding-openai — OpenAI 嵌入服务

包名: @aalis/plugin-embedding-openai
源码: packages/plugin-embedding-openai/src/index.ts

概述

OpenAI 兼容 API 的 EmbeddingService 实现，向量空间标识 modelId 为 openai:<model>。

插件声明

export default definePlugin({
  name: '@aalis/plugin-embedding-openai',
  provides: [embedding],
  uses: {
    config,
    logger,
    lifecycle,
    provide,
    contributions: optional(contributions),
  },
  apply(caps) { /* 见源码 */ },
});

配置

字段	类型	默认值	说明
apiKey	string	必填	API Key：OpenAI API 密钥（secret）
baseUrl	string	'https://api.openai.com/v1'	API 地址：API 端点完整前缀（含版本段）；插件只在其后拼 /embeddings 与 /models
model	select	'text-embedding-3-small'	Embedding 模型：用于生成文本向量的模型
timeoutMs	number	30000	请求超时 (ms)：单次 embedding 请求超时时间。不设上限时启动探测会把插件激活链整条钉住

特性

• embed() 与取模型列表的请求都带 AbortSignal.timeout(timeoutMs)。这不是可选项：apply() 会 await 一次启动连通性探测，对端不应答时，排在它后面的插件要等到慢激活阈值（默认 60 秒）它转入后台才继续激活，它自己此后也一直停在激活中；索引路径上则是 plugin-memory-vector 的一个并发槽被无限期占用

• 调用 /embeddings 端点

• 模型下拉（贡献点 webui:options 的来源 embedding-openai，即 model 字段的 dynamicOptions）从 /models 获取可用模型，只列本插件的

• apiKey 缺失时抛错

• 启动时用 embed('ping') 做一次连通性检查。apply 会等检查结束，停用或停机时中止；检查失败只记警告，服务照常注册

• 修改 baseUrl 可对接兼容 OpenAI 格式的其他 Embedding 服务（须写到完整前缀，如 http://host/v1）

配置校验

apiKey 的显式无效值、baseUrl 的错误类型、非法地址或带查询串或片段的地址（插件在它后面拼路径）会使实例进入错误态，启动连通性探测不会发请求。缺省地址仍用官方端点；timeoutMs 小于 1000 时仍夹到 1000 毫秒。