/ /

配置向量搜索的自动嵌入

注意

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.3 或更高版本。
两个 Voyage AI API密钥。

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

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

生成 Voyage AI API密钥

您可以通过以下任一路径生成 Voyage AI API密钥：

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

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

Configure `mongot` for Automated Embedding

使用两个密钥创建 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 Vector Search 索引字段。

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 可以从源文本重新生成嵌入，您需要支付嵌入生成费用。

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

要学习；了解更多信息，请参阅生成的嵌入集合。

When `mongot` Regenerates Embeddings

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

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

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

费用和速率限制

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

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

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

失败模式

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