创建文本嵌入

发布 /embeddings
API 密钥身份验证

为提供的文本输入创建向量嵌入。此端点接受单个文本字符串或文本字符串列表，并返回其相应的向量嵌入。

对于语义搜索和检索任务，请将 input_type 参数设立为 query 或 document，以优化模型创建向量的方式。

application/json

body 必需

  • 输入 string | 数组[string] 必需

    要嵌入的单个文本 string 或文本 string 列表，例如 ["I like cats", "I also like dogs"]。

    约束条件：

    • 最大列表长度：1,000 项
    • 最大令牌总数：1M（表示 voyage-3.5-lite 和 voyage-4-lite）； 320K 用于 voyage-3.5、voyage-4 和 voyage-2； 120K 用于 voyage-3-large、voyage-4-large、voyage-code-3、voyage-finance-2 和 voyage-law-2
    以下之一：
    string-1 string array-2 array[string]

    最小长度为 1。

    至少 1 个但不超过 1000 个元素。每个的最小长度为 1。

  • 模型 字符串 必需

    要使用的嵌入模型。推荐模型：voyage-4-large、voyage-4、voyage-4-lite、voyage-code-3、voyage-code-2、voyage-finance-2、voyage-law-2。

    取值为 voyage-4、voyage-4-lite、voyage-4-large、voyage-3.5、voyage-3.5-lite、voyage-3-large、voyage-code-3、voyage-finance-2、voyage-law-2 或 voyage-code-2。

  • input_type

    输入文本的类型。使用此参数可优化语义搜索和检索任务的嵌入。

    选项：

    • null （默认）：模型直接将输入转换为数值向量，而无需任何额外提示。
    • query：当输入内容表示搜索查询时使用。该模型会在前面添加“Represent the 查询 for retrieving supporting 文档:”，以优化用于检索的嵌入。
    • document：当输入内容表示要搜索的文档时使用。该模型会在前面添加“Represent the 文档 forretries:”，以优化用于检索的嵌入。

    对于语义搜索和检索任务，请务必根据情况将此参数设立为 query 或 document。使用和不使用 input_type 参数生成的嵌入是兼容的。

    值为 query、document 或 null。

  • 截断 布尔

    是否截断超过上下文长度的输入文本。

    • true （默认）：超过上下文长度的输入文本会在矢量化之前自动截断。
    • false：如果任何输入文本超过上下文长度，则会返回错误。

    默认值为true 。

  • output_dimension 整数 | null

    输出嵌入的维数。

    大多数模型仅支持单个默认维度。模型 voyage-4-large、voyage-4、voyage-4-lite、voyage-3-large、voyage-3.5、voyage-3.5-lite 和 voyage-code-3支持以下值：256、512、1024（默认）、和 2048。

    设置为 null 以使用模型的默认维度。

    值为 256、512、1024、2048 或 null。

  • output_dtype 字符串

    返回的嵌入的数据类型。

    选项：

    • float （默认）：32 位单精度浮点数。提供最高的精度和检索准确度。所有型号均支持。
    • int8：8 位有符号整数，范围从 -128 到 127。由 voyage-4-large、voyage-4、voyage-4-lite、voyage-3-large、voyage-3.5、voyage-3.5-lite 和 voyage-code-3 支持。
    • uint8：从 0 到 255 的 8 位无符号整数。由 voyage-4-large、voyage-4、voyage-4-lite、voyage-3-large、voyage-3.5、voyage-3.5-lite 和 voyage-code-3 支持。
    • binary：位打包、量化的单位嵌入值，表示为 int8。返回的列表长度为 output_dimension 的 1/8。使用偏移二进制方法。由 voyage-4-large、voyage-4、voyage-4-lite、voyage-3-large、voyage-3.5、voyage-3.5-lite 和 voyage-code-3 支持。
    • ubinary：位打包、量化的单位嵌入值，表示为 uint8。返回的列表长度为 output_dimension 的 1/8。由 voyage-4-large、voyage-4、voyage-4-lite、voyage-3-large、voyage-3.5、voyage-3.5-lite 和 voyage-code-3 支持。

    取值为 float、int8、uint8、binary 或 ubinary。默认值为 float。

  • coding_format

    响应中嵌入的编码格式。

    选项：

    • null （默认）：嵌入以数组形式返回。当 output_dtype 为 float 时，每个嵌入都是一个浮点数数组。对于其他 output_dtype 值（int8、uint8、binary、ubinary），每个嵌入都是一个整数数组。
    • base64：嵌入以 Base64 编码的 NumPy 数组的形式返回，具有以下数据类型：
      • numpy.float32 当 output_dtype 为 float 时
      • numpy.int8 当 output_dtype 为 int8 或 binary 时
      • numpy.uint8 当 output_dtype 为 uint8 或 ubinary 时

    值为 base64 或 null。

响应

  • 200 application/json

    Success

    隐藏响应属性 显示响应属性 对象
    • 对象 字符串 必需

      Realm 对象类型。始终返回“列表”。

      值为 list。

    • 数据 大量[对象] 必需

      一个数组的嵌入对象，每个输入文本对应一个嵌入对象。

      隐藏数据属性 显示数据属性 对象
      • 对象 字符串 必需

        Realm 对象类型。始终返回“embedding”。

        值为 embedding。

      • 内嵌 数组[number] | string 必需

        嵌入向量。格式取决于 encoding_format 参数：

        • 当 encoding_format 为 null 时：数字数组（当 output_dtype 为 float 时为浮点数，为 int8、uint8、binary 和 ubinary 时为整数）
        • 当 encoding_format 为 base64 时：Base64 编码的 string
        以下之一：
        大量-1 大量[number] string-2 string

        数组格式（encoding_format 为 null 时）

        Base64 编码格式（当 Encoding_format 为 base64 时）

      • 索引（index） 整型 必需

        此嵌入在输入列表中的索引。

    • 模型 字符串 必需

      用于生成嵌入的模型的名称。

    • 使用 对象 必需
      隐藏用法属性 显示用法属性 对象
      • total_tokens 整型 必需

        在所有输入文本中处理的词元总数。
  • 400 application/json

    Invalid Request

    隐藏响应属性 显示响应属性 对象
    • 详细信息 字符串

      请求无效。发生此错误的原因可能是无效的JSON、无效的参数类型、不正确的数据类型、批处理过大、词元总数超过限制或示例中的词元超过上下文长度。
  • 401 application/json

    Unauthorized

    隐藏响应属性 显示响应属性 对象
    • 详细信息 字符串

      身份验证无效。确保您的模型API密钥在授权标头中正确指定为 Bearer VOYAGE_API_KEY。
  • 403 application/json

    Forbidden

    隐藏响应属性 显示响应属性 对象
    • 详细信息 字符串

      禁止访问。如果发送请求的IP不被允许，则可能会发生这种情况。
  • 429 application/json

    已超过速率限制

    隐藏响应属性 显示响应属性 对象
    • 详细信息 字符串

      已超出速率限制。您的请求频率或令牌使用量过高。降低请求速率或等待后再重试。
  • 500 application/json

    内部服务器错误

    隐藏响应属性 显示响应属性 对象
    • 详细信息 字符串

      服务器出现意外错误。短暂等待后重试请求。
  • 502 application/json

    错误网关

    隐藏响应属性 显示响应属性 对象
    • 详细信息 字符串

      服务器从上游服务器收到无效响应。短暂等待后重试请求。
  • 503 application/json

    服务不可用

    隐藏响应属性 显示响应属性 对象
    • 详细信息 字符串

      由于流量过大或进行维护，该服务暂时不可用。短暂等待后重试请求。
  • 504 application/json

    网关超时

    隐藏响应属性 显示响应属性 对象
    • 详细信息 字符串

      服务器未收到来自上游服务器的及时响应。短暂等待后重试请求。
POST /embeddings 
curl \
 --request POST 'https://ai.mongodb.com/v1/embeddings' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "input": "string",
  "model": "voyage-4",
  "input_type": "query",
  "truncation": true,
  "output_dimension": 256,
  "output_dtype": "float",
  "encoding_format": "base64"
}'
请求示例 
{
  "input": "string",
  "model": "voyage-4",
  "input_type": "query",
  "truncation": true,
  "output_dimension": 256,
  "output_dtype": "float",
  "encoding_format": "base64"
}
响应示例 (200) 
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        42.0
      ],
      "index": 42
    }
  ],
  "model": "string",
  "usage": {
    "total_tokens": 42
  }
}
响应示例 (400) 
{
  "detail": "string"
}
响应示例 (401) 
{
  "detail": "string"
}
响应示例 (403) 
{
  "detail": "string"
}
响应示例 (429) 
{
  "detail": "string"
}
响应示例 (500) 
{
  "detail": "string"
}
响应示例 (502) 
{
  "detail": "string"
}
响应示例 (503) 
{
  "detail": "string"
}
响应示例 (504) 
{
  "detail": "string"
}