/ /

配置向量搜索的自动嵌入

注意

Automated Embedding is in Preview for mongot in Kubernetes cluster. The feature and corresponding documentation might change at any time during the Preview period. To learn more, see Preview Features.

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

This tutorial is for developers who are building semantic search or RAG features and want mongot to manage embeddings.

自动嵌入的功能

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

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

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

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

支持的嵌入提供商

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

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

You incur costs for embedding generation. To learn more, see Manage Billing for Automated Embedding.

先决条件

mongot Kubernetes 部署中的 1.70.1 或更高版本。
MongoDB 8.3 或更高版本。
Two Voyage AI API keys.

Use two separate keys, one for index-time embedding generation and one for query-time. Separate keys isolate query workload from indexing workload and allow independent rate-limit accounting. To learn more, see Rate Limits.
从 mongot 到嵌入终结点的出站网络访问。

The default endpoint is https://ai.mongodb.com/v1/embeddings, which proxies Voyage AI with MongoDB-managed billing, for keys generated using the Atlas UI. You can also use https://api.voyageai.com/v1/embeddings for direct Voyage AI access if you generated the API key directly from Voyage AI.

Generate Voyage AI API Keys

You can generate Voyage AI API keys through either of the following paths:

(Recommended) Through your Atlas account. Atlas provides API key management with built-in rate-limit configuration. The keys are not tied to an Atlas cluster. To learn more, see Manage API Keys.
Through Voyage AI directly at voyageai.com.

生成两个密钥并清楚命名，例如 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 资源规范。

创建自动嵌入索引

After you configure mongot with your Voyage AI API keys, define a Vector Search index that uses the autoEmbed field type. The index definition specifies which text field mongot embeds, which model it uses, the indexing method, quantization, and other parameters. To learn more about the autoEmbed index definition, see MongoDB Vector Search Index Fields.

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`	The Voyage AI model name. The model must be one that your API key has access to.
`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" }
      }
   }]);'

To learn more, see Run Vector Search ANN and ENN Queries.

嵌入存储

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

Changes to the embedding model, output dimensions, or quantization trigger a full re-embedding of the affected index. You incur charges for the regeneration. To learn more, see When mongot Regenerates Embeddings.

To learn more, see Generated Embeddings Collection.

When `mongot` Regenerates Embeddings

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

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

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

费用和速率限制

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

If you use the Voyage AI API key that you created using your Atlas account, you can view API key usage and rate limits in the Atlas UI. To learn more, see Manage Billing for the Embedding and Reranking API. If you use keys created directly from Voyage AI, you must monitor your usage and rate limits in the Voyage AI dashboard.

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

失败模式

症状	可能的原因
索引在 `PENDING` 状态下保持几分钟。	`mongot` cannot reach the embedding endpoint, or the API key is invalid. Check `mongot` logs for HTTP errors against the embedding endpoint.
索引延迟会间歇性地出现。	Voyage AI 端速率限制。增加速率限制或减少索引时间嵌入负载。
针对索引的查询返回一个提及嵌入的错误。	The query API key is invalid or expired. Verify the contents of `queryKeyFile`.
对索引的所有查询都返回空结果。	索引可能已经重建，并且仍在重新嵌入语料。使用 `db.collection.getSearchIndexes()` 检查索引状态。

限制

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