跳到主要内容

在其他插件中使用服务

从 @dsh-ai-providers/core 导入公共类型，再通过 Cordis 注入声明每项运行时服务。使用方代码无需依赖具体厂商包。

服务列表、公共调用选项和稳定错误码请参阅核心契约参考。

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

export const inject = ['embeddings']

export function apply(ctx: Context) {
  ctx.on('ready', async () => {
    const {vectors} = await ctx.embeddings.embed(['第一份文档', '第二份文档'])
    ctx.logger.info('received %d vectors', vectors.length)
  })
}

如果缺少该能力时插件仍可运行，请使用可选注入：

export const inject = { optional: ['streamingSpeechToText'] }

所选服务负责处理凭据、端点和厂商传输细节。直接导入厂商包会绕过这条边界，也会让提供方选择失去作用。

选择必需注入或可选注入​

如果缺少该服务时插件无法完成其公开功能，应使用必需注入。DSH 会据此控制启动顺序，并在依赖缺失时直接报告，而不是等到第一次调用才失败。只有在确有替代路径，或能彻底关闭相关功能时，才使用可选注入。

能力服务会标明当前的 provider 与 model。它们适合记录在诊断信息中，但不应成为分支到厂商专属请求代码的依据。若使用方确实需要某项厂商扩展，应明确声明该依赖，而不是假设当前选择的提供方支持它。

优先级与取消​

支持的能力调用可接收公共调用选项：

const result = await ctx.rerankers.rerank(query, documents, {
  priority: 'background',
  signal: abortController.signal,
})

阻塞当前用户操作的工作使用前台优先级；索引、预取和维护任务使用后台优先级。当调用方具有明确的取消生命周期时，应传入 AbortSignal。

流​

请完整消费或明确取消返回的流。流完成或被丢弃之前，并发门控会持续占用容量。

实时转录前先检查 ctx.streamingSpeechToText 是否存在。按照核心接口创建会话、依次发送音频块、消费转录事件，最后关闭或中止会话。

管理本地模型​

ctx.aiModels 按 LLM 路由解析模型控制能力。运行时插件加载后，该服务就会存在，但每条路由可以支持不同的操作。显示控制项或发起调用前，先检查 operations()。

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

export const inject = ['aiModels']

export async function unloadWhenIdle(ctx: Context, route: string, model: string) {
  if (!ctx.aiModels.operations(route).includes('unload')) return
  await ctx.aiModels.unload(route, model)
}

可用方法为 status(route, model)、load(route, model) 和 unload(route, model)，均可传入可选的 AbortSignal。status() 返回统一的状态；服务器报告内存用量时，结果还会包含 memoryBytes。

加载和卸载会改变提供方进程的状态，并不局限于发起调用的聊天。卸载模型可能中断正在使用同一模型的其他请求。应把这些调用绑定到明确的用户操作，或交给负责该服务器的调度器。不要在每次推理结束后自动卸载模型。

路由不存在时返回 not-configured。路由没有模型控制能力，或不支持所请求的操作时返回 unsupported。认证失败返回 rejected，传输和服务器故障返回 unavailable。

处理失败​

捕获 AiError 并根据其分类处理。错误消息只用于诊断，不属于稳定 API。包装错误时应保留原始原因。

错误码使用方应对方式
not-configured说明需要在设置中选择哪项能力。
invalid-input修正或报告调用方输入；原样重试无效。
unsupported关闭不受支持的选项，或要求兼容的提供方。
rejected简要显示配置、凭据、配额或模型错误。
unavailable仅在操作可安全重复时重试，最好加入退避。
cancelled若取消符合预期则安静结束，否则保留原始原因。

集成检查清单​

  • 只依赖 @dsh-ai-providers/core 中的契约，不依赖厂商实现。
  • 通过 Cordis 注入声明每项上下文服务。
  • 从拥有请求生命周期的一方传入 signal。
  • 将索引和维护调用标记为 background。
  • 完整消费或取消流。
  • 提供模型管理操作前，先检查 ctx.aiModels.operations(route)。
  • 将加载和卸载视为共享服务器操作，而不是聊天清理步骤。
  • 将返回的模型名、维度、令牌数、声音和媒体元数据视为提供方结果，而不是固定常量。
  • 除成功路径外，还应测试 not-configured、取消、卸载和提供方失败。