跳转至

媒体和搜索

除了文本推理之外,提供者插件还可以注册嵌入、生成和 Web 能力。在 register(api) 中,紧挨着你现有的 api.registerProvider(...) 调用,逐一注册这些能力。这是构建提供者插件指南的一部分。

打包的运行时适配器可以使用私有子路径 openclaw/plugin-sdk/concurrency-runtime 中的 createDeferred 创建延迟承诺。它返回 promise、resolve 和 reject,且无需加载日志或提供者认证;适配器仍负责取消操作和最终结算。

媒体与搜索能力

=== "嵌入" {#embeddings}

```typescript
// fetchAcmeEmbedding is your plugin's own vendor API call, not an SDK export.
api.registerEmbeddingProvider({
  id: "acme-ai",
  defaultModel: "acme-embed",
  transport: "remote",
  authProviderId: "acme-ai",
  create: async ({ model }) => ({
    provider: {
      id: "acme-ai",
      model,
      dimensions: 1536,
      embed: async (input) => {
        const text = typeof input === "string" ? input : input.text;
        return fetchAcmeEmbedding(text);
      },
      embedBatch: async (inputs) =>
        Promise.all(
          inputs.map((input) =>
            fetchAcmeEmbedding(typeof input === "string" ? input : input.text),
          ),
        ),
    },
  }),
});
```

在 `contracts.embeddingProviders` 中声明相同的 id。这是用于可复用向量生成(包括记忆搜索)的通用嵌入契约。已退役的、记忆专属的注册器和清单契约不再被接受。

兼容 OpenAI 的端点可以使用 `openclaw/plugin-sdk/memory-core-host-engine-embeddings` 中的 `createRemoteEmbeddingProvider`。其可选的 `buildRequestFields(kind)` 回调会为 `"query"` 或 `"document"` 请求返回额外的 JSON 字段,例如 `dimensions` 或 `input_type`。共享工厂始终在这些字段之后提供客户端的 `model` 和原始 `input` 数组,从而保持响应数量验证。

`embed` 和 `embedBatch` 接受可选的 `onUsage` 调用选项。上报用量的提供者会在每次上游请求成功后、解析(resolve)之前调用它一次,传入 `{ promptTokens, totalTokens }`;若该响应没有有效计数,则传入 `undefined`。调用方可以汇总这些上报,并将任何不可用的响应视为不完整的用量。共享的远程工厂上报 OpenAI 风格的用量;向量返回值和现有插件保持不变。

接受模型别名的提供者可以暴露 `normalizeModel(options): string`。记忆功能在创建选项和冷索引身份检查中都会使用这个同步钩子。请保持它仅用于配置:不要进行认证或访问网络。使规范化具有幂等性,并在 `create` 中复用它——`create` 可能收到已规范化的模型,也可能在记忆场景之外被调用。仅当模型在发现之前仍然未知时才返回空字符串;不要将无效的显式模型变成省略的选择。要获得精确的预初始化身份,`resolveIndexIdentity(options)` 会额外提供所需的 `cacheKeyData` 和任何等价的持久化别名。

=== "图像与视频生成" {#image-and-video-generation}

图像和视频能力使用**模式感知(mode-aware)**的结构。图像提供者声明必需的 `generate` 和 `edit` 能力块;视频提供者声明 `generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段不足以清晰地表明转换模式支持或已禁用的模式。音乐生成遵循相同的 `generate` / `edit` 模式。

打包的提供者可以使用私有子路径 `openclaw/plugin-sdk/video-generation` 中的 `selectSupportedVideoDuration`,从非空列表中选择最接近的值,平局时优先选择较长的时长。请将输入验证、舍入、边界和默认时长保留在提供者中。

```typescript
api.registerImageGenerationProvider({
  id: "acme-ai",
  label: "Acme Images",
  capabilities: {
    generate: { maxCount: 4, supportsSize: true },
    edit: { enabled: false },
  },
  generateImage: async (req) => ({
    images: [
      {
        buffer: await generateAcmeImageBytes(req),
        mimeType: "image/png",
        fileName: "acme-image.png",
      },
    ],
  }),
});

api.registerVideoGenerationProvider({
  id: "acme-ai",
  label: "Acme Video",
  defaultTimeoutMs: 600_000,
  models: ["acme-video", "acme-image-video"],
  capabilities: {
    generate: { maxVideos: 1, maxDurationSeconds: 10, supportsResolution: true },
    imageToVideo: {
      enabled: true,
      maxVideos: 1,
      maxInputImages: 1,
      maxInputImagesByModel: { "acme/reference-to-video": 9 },
      maxDurationSeconds: 5,
    },
    videoToVideo: { enabled: false },
  },
  catalogByModel: {
    "acme-image-video": {
      modes: ["imageToVideo"],
      capabilities: {
        imageToVideo: {
          enabled: true,
          maxVideos: 1,
          maxInputImages: 1,
          resolutions: ["480P", "720P", "1080P"],
          supportsResolution: true,
        },
        videoToVideo: { enabled: false },
      },
    },
  },
  generateVideo: async (req) => ({
    videos: [
      {
        url: await generateAcmeVideoUrl(req),
        mimeType: "video/mp4",
      },
    ],
  }),
});
```

示例中的辅助函数代表提供者调用:图像辅助函数返回非空的编码字节,视频辅助函数则返回托管的媒体 URL。视频提供者也可以返回非空的编码字节;当 URL 只是交付回退时,也可以同时返回两者。空的结果数组和空缓冲区会被视为潜在失败,唯一的例外是:具有可用 URL 的视频资产会忽略空缓冲区并继续使用 URL。

capabilities 在两种 provider 类型上都是必填的;edit 以及视频转换块(imageToVideo、videoToVideo)始终需要显式的 enabled 标志。

当所列模型的静态模式或能力与 provider 默认值不同时,使用 catalogByModel。此元数据使 video_generate action=list 和模型目录保持准确,而无需调用 provider 代码。请求时的能力查找与强制检查仍属于 resolveModelCapabilities 和 generateVideo 的职责;尽可能在两条路径中复用同一个能力常量。

以下 私有本地辅助工具 仅支持随附打包和单独发布的官方插件。

对于异步 provider 任务,来自 openclaw/plugin-sdk/provider-http 的 pollProviderOperation 共享有界轮询循环,而插件提供其请求、完成/失败检查以及等待函数。pollProviderOperationJson 添加了标准 HTTP JSON 传输。将供应商认证和截止时间范围保留在 provider 适配器中。

当自定义响应体读取器耗尽同一截止时间时,复用 createProviderOperationTimeoutError(deadline)。它会在共享错误格式中保留操作标签和可选超时时间。

来自 openclaw/plugin-sdk/media-generation-runtime 的 readGeneratedVideoAsset 会在字节上限内读取响应,并推导出资源的 MIME 类型和文件名。设置 validateBinaryResponse 以拒绝非视频响应。可选的 overflowUrl 仅在响应体超过该上限时提供交付;格式错误的媒体和传输错误仍然会失败。调用方负责响应清理。downloadGeneratedVideoAsset 同样负责获取、截止时间和清理。

api.registerWebFetchProvider({
  id: "acme-ai-fetch",
  label: "Acme Fetch",
  hint: "Fetch pages through Acme's rendering backend.",
  envVars: ["ACME_FETCH_API_KEY"],
  placeholder: "acme-...",
  signupUrl: "https://acme.example.com/fetch",
  credentialPath: "plugins.entries.acme.config.webFetch.apiKey",
  getCredentialValue: (fetchConfig) => fetchConfig?.acme?.apiKey,
  setCredentialValue: (fetchConfigTarget, value) => {
    const acme = (fetchConfigTarget.acme ??= {});
    acme.apiKey = value;
  },
  createTool: () => ({
    description: "Fetch a page through Acme Fetch.",
    parameters: {},
    execute: async (args) => ({ content: [] }),
  }),
});

api.registerWebSearchProvider({
  id: "acme-ai-search",
  label: "Acme Search",
  hint: "Search the web through Acme's search backend.",
  envVars: ["ACME_SEARCH_API_KEY"],
  placeholder: "acme-...",
  signupUrl: "https://acme.example.com/search",
  credentialPath: "plugins.entries.acme.config.webSearch.apiKey",
  getCredentialValue: (searchConfig) => searchConfig?.acme?.apiKey,
  setCredentialValue: (searchConfigTarget, value) => {
    const acme = (searchConfigTarget.acme ??= {});
    acme.apiKey = value;
  },
  createTool: () => ({
    description: "Search the web through Acme Search.",
    parameters: {},
    execute: async (args) => ({ content: [] }),
  }),
});

两种 provider 类型共享相同的凭据接线结构:hint、envVars、placeholder、signupUrl、credentialPath、getCredentialValue、setCredentialValue 和 createTool 都是必填项。

搜索 provider 可以将 configPath 声明为相对于其自身插件配置的路径,用于搜索设置页面。它默认为 ["webSearch"];当 provider 没有内联设置时使用 null。共享同一插件的 provider 可以公开不同的设置,而不会显示仅适用于同级 provider 的字段。凭据仍由 credentialPath 描述,并使用现有的掩码凭据编辑器。

使用 openclaw/plugin-sdk/provider-web-search 的搜索 provider 应在每次执行时解析一次 resolveSearchCacheTtlMs(searchConfig),并将该值同时传给 readCachedSearchPayload(cacheKey, ttlMs) 和 writeCachedSearchPayload(cacheKey, payload, ttlMs)。零 TTL 会绕过读取和写入;正 TTL 限制条目存活时间,但不会延长其原始过期时间。读取会返回标记为 cached: true 的负载,未命中时返回 undefined。读取器的 ttlMs 参数是可选的:现有单参数调用仍仅使用已存储的过期时间。

两个工具定义都接受 execute(args, context?),其中可选上下文携带 signal?: AbortSignal。请将该信号转发给网络请求,并在异步工作后检查取消状态。现有的单参数实现仍然有效;OpenClaw 会在取消后拒绝迟到的抓取结果,然后再将其发布到抓取缓存。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw