/ /

配置向量搜索的自动嵌入

注意

Kubernetes 集群中 mongot 的自动嵌入处于预览阶段。在预览期间，该功能和相应文档可能会随时更改。要了解更多信息，请参阅预览功能。

本页介绍如何在 Kubernetes 部署的向量搜索上配置自动嵌入。向量搜索中的自动嵌入功能在索引时间为文本数据生成向量嵌入，在查询时间为查询文本生成向量嵌入。因此，您不必在应用程序中维护单独的嵌入管道。

本教程适用于开发者，他们正在构建语义搜索或 RAG 功能，并希望 mongot 管理嵌入。

自动嵌入的功能

无自动嵌入，您的应用程序必须：

为插入或更新的每个文档生成嵌入。
将该嵌入与集合中的文档一起存储。
在查询时间使用相同模型为每个查询生成嵌入。
向 $vectorSearch 提交查询嵌入。

使用自动嵌入，mongot 进程处理步骤 1、2 和 3。您的应用程序：

为文本字段配置具有 autoEmbed 字段类型的向量搜索索引。
正常插入和更新文档。然后，mongot 读取文本字段，通过配置的嵌入模型生成嵌入，并将其存储起来。
使用查询文本而非预计算嵌入发出 $vectorSearch 查询。然后，mongot 为查询文本生成嵌入。

支持的嵌入提供商

自管理 mongot 自动嵌入与 Voyage AI 嵌入模型集成。

模型	说明
`voyage-4-lite`	大容量、成本敏感的应用程序。
`voyage-4`	推荐。平衡一般文本搜索的性能。
`voyage-4-large`	复杂语义关系的最高准确性。
`voyage-code-3`	专门用于代码搜索和技术文档。

您需要支付嵌入生成的费用。要学习更多信息，请参阅管理自动嵌入的计费。

先决条件

mongot Kubernetes 部署中的 1.70.1 或更高版本。
MongoDB 8.2 或更高版本。
两个 Voyage AI API 密钥。

使用两个独立的密钥，一个用于索引时间嵌入生成，一个用于查询时间。独立密钥可以将查询工作负载与索引工作负载隔离，并允许独立的速率限制计费。要学习；了解更多信息，请参阅速率限制。
从 mongot 到嵌入终结点的出站网络访问。

默认终结点是 https://ai.mongodb.com/v1/embeddings，它使用 MongoDB 托管的计费对 Voyage AI 进行代理，以实现使用 Atlas 用户界面生成的密钥。如果您直接从 Voyage AI 生成了 API 密钥，则还可以使用 https://api.voyageai.com/v1/embeddings 直接访问 Voyage AI。

生成 Voyage AI API 密钥

您可以通过以下任一种方式生成 Voyage AI API 密钥：

（推荐）通过 Atlas 账户。Atlas 提供具有内置限速配置的 API 密钥管理。密钥不与 Atlas 集群绑定。要了解更多信息，请参阅管理 API 密钥。
通过 voyageai.com 直接访问 Voyage AI。

生成两个密钥并清楚命名，例如 mongot-prod-index 和 mongot-prod-query。将密钥存储在安全秘密存储中。

配置 `mongot` 以实现自动嵌入

使用两个密钥创建 Kubernetes Secret：

kubectl create secret generic voyage-api-keys \
  --from-literal=indexing-key=<your-index-key> \
  --from-literal=query-key=<your-query-key> \
  --namespace=<your-namespace>

从 MongoDBSearch 自定义资源参考它：

apiVersion: mongodb.com/v1
kind: MongoDBSearch
metadata:
  name: mdbs
spec:
  # ...
  autoEmbedding:
    embeddingModelAPIKeySecret:
      name: voyage-api-keys

可选地，将 spec.autoEmbedding.providerEndpoint 设置为覆盖 mongot 使用的嵌入终结点。当您忽略此字段时，mongot 会使用其内置默认终结点 https://ai.mongodb.com/v1/embeddings。要了解更多信息，请参阅 MongoDBSearch 资源规范。

创建自动嵌入索引

使用 Voyage AI API 密钥配置 mongot 后，定义使用 autoEmbed 字段类型的向量搜索索引。索引定义指定 mongot 嵌入的文本字段、其使用的模型、索引方法、量化和其他参数。要进一步了解 autoEmbed 索引定义，请参阅 MongoDB 向量搜索索引字段。

kubectl exec --context "${K8S_CTX}" -n "${MDB_NS}" mongodb-tools-pod -- \
mongosh --quiet "${MDB_CONNECTION_STRING}" \
   --eval "use sample_mflix" \
   --eval 'db.movies.createSearchIndex("vector_auto_embed_index", "vectorSearch",
      { "fields": [ {
         "type": "autoEmbed",
         "modality": "text",
         "path": "plot",
         "model": "'"${EMBEDDING_MODEL}"'",
         "numDimensions": 1024,
         "similarity": "cosine",
         "quantization": "scalar",
         "indexingMethod": "hnsw",
         "hnswOptions": {
            "maxEdges": 16,
            "numEdgeCandidates": 200
         }
      } ] });'

下表描述了 autoEmbed 索引定义字段：

字段	用途
`type: "autoEmbed"`	将字段标记为自动嵌入。
`modality: "text"`	数据模态。`text` 是唯一支持的模态。
`path`	要嵌入的集合中的字段。
`model`	Voyage AI 模型名称。该模型必须是您的 API 密钥可以访问的模型。
`numDimensions`	嵌入向量的维数。该模型确定支持的维数。
`similarity`	用于向量搜索的相似度函数。支持的函数是 `cosine`、`dotProduct` 和 `euclidean`。
`indexingMethod`	要使用的索引方法。支持的方法是 `flat` 和 `hnsw`。
`hnswOptions`	（可选）HNSW 索引选项。如果 `indexingMethod` 是 `hnsw`，则为必填项。
`quantization`	（可选）要使用的量化类型。支持的类型有 `float`、`scalar`、`binary` 和 `binaryNoRescore`。

您可以在同一索引中混合 autoEmbed 字段和 filter 字段。您不能在同一路径上将 autoEmbed 与原始向量字段混合。

运行自动嵌入查询

提交查询文本，而不是预计算的嵌入。mongot 为您生成查询嵌入。

kubectl exec --context "${K8S_CTX}" -n "${MDB_NS}" mongodb-tools-pod -- \
mongosh --quiet "${MDB_CONNECTION_STRING}" \
   --eval "use sample_mflix" \
   --eval 'db.movies.aggregate([ {
      $vectorSearch: {
         index: "vector_auto_embed_index",
         path: "plot",
         query: "spy thriller",
         numCandidates: 150,
         limit: 10
      }
   }, {
      $project: {
         _id: 0,
         plot: 1,
         title: 1,
         score: { $meta: "vectorSearchScore" }
      }
   }]);'

要学习；了解更多信息，请参阅运行向量搜索 ANN 和 ENN 查询。

嵌入存储

mongot 在 Kubernetes 集群上的专用内部数据库中持久化嵌入。mongot 不会在源集合中存储嵌入。mongot 可以从源文本重新生成嵌入，您需要支付嵌入生成费用。

对嵌入模型、输出维度或量化的更改会 trigger 受影响索引的完全重新嵌入。您将支付重新生成的费用。要了解更多信息，请参阅 mongot 重新生成嵌入的时候。

要了解更多，请参阅生成的嵌入集合。

当 `mongot` 重新生成嵌入时

mongot 在发生以下任何情况时，会重新生成 autoEmbed 字段的嵌入：

您插入一个文档。
您更改文档中的嵌入字段。mongot 通过变更流检测到更改。
您在索引定义中更改嵌入模型。
您更改嵌入输出维度或数据类型。
您更改了字段路径（Field Path）。

如果您更改任何后三个项，mongot 将从头开始重建整个索引。对于大型集合，重建成本可能很高。计划模型变更。

费用和速率限制

MongoDB 按模型特定费率按百万个令牌收费。索引费用与集合中索引字段的总文本量成正比。查询费用与查询文本量成正比。

如果您使用通过 Atlas 账户创建的 Voyage AI API 密钥，则可以在 Atlas 用户界面中查看 API 密钥使用情况和速率限制。要学习；了解更多信息，请参阅管理 Embedding and Reranking API 的计费。如果您使用直接从 Voyage AI 创建的密钥，则必须在 Voyage AI 仪表盘中监控使用情况和速率限制。

Voyage AI 侧的速率限制错误会出现在 mongot 日志中，并作为受影响索引上的失败文档指示符。这些错误不会禁用索引，但会延迟新文档的索引。

失败模式

症状	可能的原因
索引在 `PENDING` 状态下保持几分钟。	`mongot` 无法访问嵌入终结点，或 API 密钥无效。检查 `mongot` 日志中针对嵌入终结点的 HTTP 错误。
索引延迟会间歇性地出现。	Voyage AI 端速率限制。增加速率限制或减少索引时间嵌入负载。
针对索引的查询返回一个提及嵌入的错误。	查询 API 密钥无效或已过期。验证 `queryKeyFile` 的内容。
对索引的所有查询都返回空结果。	索引可能已经重建，并且仍在重新嵌入语料。使用 `db.collection.getSearchIndexes()` 检查索引状态。

限制

预览状态。在自动嵌入普遍可用之前，配置形状、支持的模型和默认终结点可能会发生变化。
每个字段一个嵌入模型。不支持混合模型索引。
无嵌入模型故障转移。如果 Voyage AI 终结点无法访问，则新文档的索引将停滞。

后退

配置 mongot

来年

配置安全性：MongoDB 到搜索