您可以将任何文本嵌入生成器与 Meilisearch 集成，只要您选择的提供商提供公共 REST API。

将 REST 嵌入器与 Meilisearch 集成的过程因提供商及其数据结构而异。本指南将展示如何查找所需信息，并基于这些信息逐步配置您的 Meilisearch 嵌入器。

​
查找嵌入器提供商的文档

每个提供商都要求查询遵循特定的数据结构。

在开始创建嵌入器之前，请先找到您提供商关于嵌入生成的文档。其中应包含有关 API 请求、请求头和响应的必要信息。

例如，Mistral 的嵌入文档是其 API 参考的一部分。而对于 Cloudflare 的 Workers AI，预期的输入和响应则与您选择的模型相关。

​
设置 REST 源和 URL

打开文本编辑器并创建一个嵌入器对象。为其命名并将源设置为 "rest"：

{
  "EMBEDDER_NAME": {
    "source": "rest"
  }
}

接着配置 Meilisearch 用于联系嵌入提供商的 URL：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL"
  }
}

为所有 REST 嵌入器设置嵌入器名称、source 和 url 是必需的。

​
配置 Meilisearch 发送给提供商的数据

Meilisearch 的 request 字段定义了它将发送给提供商的输入结构。不同提供商需要以不同方式填充此字段。

例如，Mistral 需要两个必填参数：model 和 input，以及一个可选参数 encoding_format。而 Cloudflare 则只需要单个字段 text。

​
选择模型

许多情况下，您的提供商要求您明确设置用于创建嵌入向量的模型。例如在 Mistral 中，model 必须是一个指定有效 Mistral 模型的字符串。

更新您的 embedder 对象，添加以下字段及其值：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME"
    }
  }
}

对于 Cloudflare 的情况，模型是 API 路由本身的一部分，不需要在您的 request 中特别指定。

​
嵌入提示词 (embedding prompt)

提示词对应着供应商用来生成文档嵌入向量的数据。其具体名称会根据您选择的供应商而变化。在 Mistral 中，这个字段称为 input。在 Cloudflare 中则叫做 text。

大多数供应商接受字符串或字符串数组作为输入。单个字符串会为数据库中的每个文档生成一个请求：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "input": "{{text}}"
    }
  }
}

{{text}} 表示 Meilisearch 应该用文档数据替换该字段内容，具体字段由嵌入器的 documentTemplate 指定。

使用字符串数组允许 Meilisearch 在一个请求中发送最多 10 个文档，减少对供应商的 API 调用次数：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "input": [
        "{{text}}", 
        "{{..}}"
      ]
    }
  }
}

使用数组提示词时，第一项必须是 {{text}}。如果您想在一个请求中发送多个文档，第二项数组元素必须是 {{..}}。当使用 "{{..}}" 时，它必须同时在 request 和 response 中出现。

使用其他嵌入供应商时，input 可能被称为其他名称，例如 text 或 prompt：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "text": "{{text}}"
    }
  }
}

​
提供其他请求字段

您可以根据需要在 request 对象中添加任意数量的字段。Meilisearch 在查询 embeddings 提供商时会包含这些字段。

例如，Mistral 允许您可选地配置 encoding_format。通过在 embedder 的 request 中声明该字段来设置：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "input": ["{{text}}", "{{..}}"],
      "encoding_format": "float"
    }
  }
}

​
嵌入响应处理

您需要指定 Meilisearch 从提供商的响应中获取文档嵌入向量的位置。请查阅您所用提供商的 API 文档，特别注意其返回嵌入向量的位置。

例如 Cloudflare 的嵌入向量位于 response.result.data 数组内。在您的嵌入器配置中，需要完整描述到嵌入数组的路径。第一个数组项必须是 "{{embedding}}"：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "text": "{{text}}"
    },
    "response": {
      "result": {
        "data": ["{{embedding}}"]
      }
    }
  }
}

如果响应包含多个嵌入向量，使用 "{{..}}" 作为第二个值：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "input": [
        "{{text}}", 
        "{{..}}"
      ]
    },
    "response": {
      "data": [
        {
          "embedding": "{{embedding}}"
        },
        "{{..}}"
      ]
    }
  }
}

当使用 "{{..}}" 时，它必须同时在 request 和 response 中出现。

有时响应可能包含一个不在数组中的单独嵌入向量。此时使用 "{{embedding}}" 作为其值：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "input": "{{text}}"
    },
    "response": {
      "data": {
        "text": "{{embedding}}"
      }
    }
  }
}

响应也可能是未嵌套在对象中的单个项或数组：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "input": [
        "{{text}}",
        "{{..}}"
      ]
    },
    "response": [
      "{{embedding}}",
      "{{..}}"
    ]
  }
}

提示数据类型不一定与响应数据类型匹配。例如 Cloudflare 总是返回嵌入向量数组，即使您请求中的提示是字符串。

Meilisearch 会静默忽略未指向 "{{embedding}}" 值的 response 字段。

​
嵌入请求头配置

您的服务提供商可能要求您在请求中添加特定的头部信息。例如，Azure 的 AI 服务需要一个包含 API 密钥的 api-key 请求头。

在嵌入器对象中添加 headers 字段：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "text": "{{text}}"
    },
    "response": {
      "result": {
        "data": ["{{embedding}}"]
      }
    },
    "headers": {
      "FIELD_NAME": "FIELD_VALUE"
    }
  }
}

默认情况下，Meilisearch 会自动包含 Content-Type 请求头。如果您提供了 API 密钥，系统还会自动包含授权承载令牌。

​
配置嵌入器的其余部分

source、request、response 和 header 是 REST 嵌入器特有的字段。

与其他远程嵌入器类似，您可能需要提供 apiKey：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "input": ["{{text}}", "{{..}}"],
      "encoding_format": "float"
    },
    "response": {
      "data": [
        {
          "embedding": "{{embedding}}"
        },
        "{{..}}"
      ]
    },
    "apiKey": "PROVIDER_API_KEY",
  }
}

您还应该设置 documentTemplate。好的模板应该简短且只包含高度相关的文档数据：

{
  "EMBEDDER_NAME": {
    "source": "rest",
    "url": "PROVIDER_URL",
    "request": {
      "model": "MODEL_NAME",
      "input": ["{{text}}", "{{..}}"],
      "encoding_format": "float"
    },
    "response": {
      "data": [
        {
          "embedding": "{{embedding}}"
        },
        "{{..}}"
      ]
    },
    "apiKey": "PROVIDER_API_KEY",
    "documentTemplate": "SHORT_AND_RELEVANT_DOCUMENT_TEMPLATE"
  }
}

​
更新索引设置

现在 embedder 对象已配置完成，更新您的索引设置：

curl \
  -X PATCH 'MEILISEARCH_URL/indexes/INDEX_NAME/settings/embedders' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "EMBEDDER_NAME": {
      "source": "rest",
      "url": "PROVIDER_URL",
      "request": {
        "model": "MODEL_NAME",
        "input": ["{{text}}", "{{..}}"],
      },
      "response": {
        "data": [
          {
            "embedding": "{{embedding}}"
          },
          "{{..}}"
        ]
      },
      "apiKey": "PROVIDER_API_KEY",
      "documentTemplate": "SHORT_AND_RELEVANT_DOCUMENT_TEMPLATE"
    }
  }'

​
总结

在本指南中，您已经了解了如何在 Meilisearch 中配置 REST embedder 的几个示例。虽然示例中使用了 Mistral 和 Cloudflare，但对于所有提供商来说，通用步骤都是相同的：

  1. 查找提供商的 REST API 文档
  2. 确定创建嵌入的请求参数
  3. 将这些参数包含在 embedder 的 request 中
  4. 确定创建嵌入的响应格式
  5. 在 embedder 的 response 中重现返回嵌入的路径
  6. 将所需的 HTTP 头添加到 embedder 的 header 中
  7. 使用新的 embedder 更新索引设置