Astra DB 语义检索：JSON 与向量搜索结合指南

本文深入介绍了如何在 Astra DB 中利用其原生 JSON API 实现结构化数据与语义向量搜索的无缝融合——无需额外向量数据库，只需在 JSON 文档中嵌入 `$vector` 字段并调用标准 REST 接口，即可完成向量化存储与近似最近邻（ANN）检索；文章不仅详解了认证配置、文档插入、相似度查询等核心操作，还特别提醒了维度匹配、字段保留、协议兼容性（如不支持 MongoDB 的 Mongoose）等关键实践陷阱，并提供了可直接复用的 JavaScript 工具函数和生产级安全建议，为构建智能推荐、语义搜索等 AI 原生应用提供了简洁、高效、开箱即用的数据层解决方案。

Astra DB 提供原生 JSON API，支持在存储结构化 JSON 文档的同时，为字段嵌入向量（$vector），并直接通过近似最近邻（ANN）查询实现语义搜索，无需额外向量数据库。

Astra DB 提供原生 JSON API，支持在存储结构化 JSON 文档的同时，为字段嵌入向量（`$vector`），并直接通过近似最近邻（ANN）查询实现语义搜索，无需额外向量数据库。

在 Astra DB 中融合 JSON 数据建模与向量搜索能力，关键在于使用其 JSON API（非 CQL 或 GraphQL 接口），该接口专为开发者友好型文档操作设计，并原生支持向量嵌入的存储与 ANN 检索。虽然你当前使用 Mongoose（面向 MongoDB 的 ODM），但需注意：Astra DB 不兼容 MongoDB 协议，因此不能直接复用 Mongoose 连接或 Schema；你应改用 Astra DB 官方推荐的 HTTP/REST 方式（即 JSON API）进行交互。

✅ 正确集成方式：基于 JSON API 的向量化文档操作

所有操作均通过标准 HTTPS 请求完成，需提供以下认证头：

• X-Cassandra-Token: 应用令牌（Application Token），在 Astra 控制台生成；
• Content-Type: application/json 与 Accept: application/json。

▪ 插入带向量的 JSON 文档

向量必须以 $vector 字段名显式声明，值为浮点数数组（长度需与集合创建时指定的维度一致）：

curl -s --location \
  --request POST "https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection" \
  --header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "insertOne": {
      "document": {
        "_id": "4",
        "name": "Coded Cleats Copy",
        "description": "ChatGPT integrated sneakers that talk to you",
        "$vector": [0.25, 0.25, 0.25, 0.25, 0.25]
      }
    }
  }'

⚠️ 注意：vector_collection 必须是已启用向量搜索的集合（创建时需指定 vector 选项及维度，例如 {"dimension": 5}）。未配置向量支持的集合将拒绝含 $vector 的写入请求。

▪ 执行向量相似度搜索（ANN）

使用 find 命令 + sort: {"$vector": [...]} 触发近似最近邻检索，配合 options.limit 控制返回数量：

curl -s --location \
  --request POST "https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection" \
  --header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "find": {
      "sort": {"$vector": [0.15, 0.1, 0.1, 0.35, 0.55]},
      "options": {"limit": 10}
    }
  }'

该查询将按余弦相似度（默认）或欧氏距离（取决于集合配置）对 $vector 字段排序，返回最相似的 10 条 JSON 文档，完整保留原始字段（如 name、description 等）。

? 在 JavaScript 应用中调用建议

避免裸写 curl，推荐封装为可复用的工具函数：

// utils/astra-json-api.js
const axios = require('axios');

const ASTRA_BASE_URL = `https://${process.env.ASTRA_DB_ID}-${process.env.ASTRA_DB_REGION}.apps.astra.datastax.com`;
const TOKEN = process.env.ASTRA_DB_APPLICATION_TOKEN;

async function insertVectorDoc(collection, doc) {
  const res = await axios.post(
    `${ASTRA_BASE_URL}/api/json/v1/${process.env.ASTRA_DB_KEYSPACE}/${collection}`,
    { insertOne: { document: doc } },
    {
      headers: {
        'X-Cassandra-Token': TOKEN,
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
    }
  );
  return res.data;
}

async function findSimilar(collection, queryVector, limit = 10) {
  const res = await axios.post(
    `${ASTRA_BASE_URL}/api/json/v1/${process.env.ASTRA_DB_KEYSPACE}/${collection}`,
    {
      find: {
        sort: { $vector: queryVector },
        options: { limit },
      },
    },
    {
      headers: {
        'X-Cassandra-Token': TOKEN,
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
    }
  );
  return res.data.data?.documents || [];
}

? 关键注意事项

• 向量维度必须严格匹配集合定义（如创建时设为 dimension: 384，则每次 $vector 数组长度必须为 384）；
• $vector 是保留字段名，不可用于普通索引或业务逻辑字段；
• JSON API 不支持事务、聚合管道或复杂嵌套查询，适合“文档+向量”轻量级语义检索场景；
• 如需类型安全与开发体验，可结合 TypeScript 定义文档接口，并用 Zod 验证 $vector 格式；
• 生产环境务必轮换应用令牌、限制 IP 白名单，并对敏感向量源（如用户 Embedding）做脱敏处理。

通过 JSON API，你能在 Astra DB 中真正实现「一库双模」——既享受 JSON 的灵活建模，又获得低延迟向量检索能力，为 AI 原生应用（如智能商品推荐、语义客服知识库）提供简洁可靠的后端支撑。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。