GCP Vertex Search公网端点索引基于Namespace过滤时遇DNS解析错误

DNS解析错误排查与修复 #

错误提示DNS resolution failed for :10000: unparseable host:port说明客户端无法正确识别索引端点的主机地址，可按以下步骤排查：

• 确认端点部署状态：在GCP控制台的Vertex AI -> 向量搜索 -> 索引端点页面，验证公网端点状态为活跃，且公网访问开关已启用。
• 升级SDK版本：旧版google-cloud-aiplatform可能存在端点地址解析bug，执行命令升级到最新稳定版：

  pip install --upgrade google-cloud-aiplatform
  

• 检查端点资源名称：调用match()时，必须传入完整的资源ID，格式为projects/[PROJECT_ID]/locations/us-central1/indexEndpoints/[ENDPOINT_ID]，不能只传端点名称。
• 核查网络规则：公网端点虽允许外部访问，但需确保VM/本地机器的出站防火墙允许TCP 10000端口的流量，避免拦截gRPC请求。

使用match()方法添加Namespace过滤 #

要基于数据点的restricts属性（Namespace）过滤，需在批量请求的每个查询项中添加restricts字段，示例代码如下：

from google.cloud import aiplatform

# 初始化客户端
aiplatform.init(project="你的项目ID", location="us-central1")

# 获取目标索引端点
index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
    index_endpoint_name="projects/你的项目ID/locations/us-central1/indexEndpoints/你的端点ID"
)

# 构造带过滤规则的批量查询请求
batch_requests = [
    {
        "datapoint": {"feature_vector": [0.1, 0.2, 0.3]},  # 替换为你的查询向量
        "restricts": [{"namespace": "目标命名空间", "allowlist": ["允许的值1", "允许的值2"]}],
        "neighbor_count": 10
    }
    # 可添加更多查询项
]

# 执行批量匹配
response = index_endpoint.match(batch_match_requests=batch_requests)

restricts字段说明：

• namespace：对应数据点restricts属性中的命名空间标识
• allowlist：指定该命名空间下允许匹配的属性值；若需匹配该命名空间下所有值，可省略allowlist或传空列表

使用aiplatform_v1.MatchServiceClient添加过滤 #

若需使用低阶客户端，可通过FindNeighborsRequest的query字段设置过滤规则，示例代码：

from google.cloud import aiplatform_v1

client = aiplatform_v1.MatchServiceClient()

# 构造单个查询（批量查询可添加多个query到queries列表）
query = aiplatform_v1.Query()
query.feature_vector = [0.1, 0.2, 0.3]
# 添加Namespace过滤规则
restrict = aiplatform_v1.Restrict()
restrict.namespace = "目标命名空间"
restrict.allowlist.extend(["允许的值1", "允许的值2"])
query.restricts.append(restrict)
query.neighbor_count = 10

# 构造请求并执行
request = aiplatform_v1.FindNeighborsRequest(
    index_endpoint="projects/你的项目ID/locations/us-central1/indexEndpoints/你的端点ID",
    deployed_index_id="你的部署索引ID",
    queries=[query]
)

response = client.find_neighbors(request=request)

内容的提问来源于stack exchange，提问作者Pravin Jade