googleapis / googleapis/python-aiplatform

Bug: create_tree_ah_index() fails when leaf parameters are not specified (regression from PR #5954)

未关闭
#6,222 0 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看
api: vertex-ai
主要语言
Python
星标
905
派生
465
平均合并
1 天 13 小时
30 天内合并 PR
44

描述

**PLEASE READ**: I have searched existing issues and StackOverflow before creating this report.

## Environment details

- OS type and version: macOS
- Python version: 3.12
- pip version: 24.0
- `google-cloud-aiplatform` version: >= 1.71.0 (after PR #5954)

## Steps to reproduce

1. Call `MatchingEngineIndex.create_tree_ah_index()` without specifying `leaf_node_embedding_count` or `leaf_nodes_to_search_percent`
2. The API returns an error: `algorithmConfig is required but missing from the metadata`

## Code example

```python
from google.cloud import aiplatform

aiplatform.init(project="my-project", location="us-central1")

# This fails
index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
display_name="my-index",
dimensions=768,
approximate_neighbors_count=150,
distance_measure_type="DOT_PRODUCT_DISTANCE",
# Note: leaf_node_embedding_count and leaf_nodes_to_search_percent are NOT specified
)
```

## Stack trace

```
algorithmConfig is required but missing from the metadata
```

---

## Additional Context

### Description

`MatchingEngineIndex.create_tree_ah_index()` fails when neither `leaf_node_embedding_count` nor `leaf_nodes_to_search_percent` is specified, because `algorithmConfig` is set to `None` instead of `{"treeAhConfig": {}}`.

According to the [official documentation](https://cloud.google.com/vertex-ai/docs/vector-search/configuring-indexes), `algorithmConfig` is a **required** field that must contain either `TreeAhConfig` or `BruteForceConfig`. Setting it to `null` causes the API to reject the request.

### Expected Behavior

The REST API expects:
```json
{
"metadata": {
"config": {
"dimensions": 768,
"approximateNeighborsCount": 150,
"algorithmConfig": {
"treeAhConfig": {}
}
}
}
}
```

### Actual Behavior

The SDK sends:
```json
{
"metadata": {
"config": {
"dimensions": 768,
"approximateNeighborsCount": 150,
"algorithmConfig": null
}
}
}
```

### Root Cause

This regression was introduced in PR #5954 (merged 2025-10-21).

The intent of PR #5954 was to make the `treeAhConfig` parameters (`leaf_node_embedding_count`, `leaf_nodes_to_search_percent`) optional. However, the implementation incorrectly sets `algorithmConfig` itself to `None` instead of sending an empty `treeAhConfig: {}`.

**Before PR #5954** (`matching_engine_index.py`):
```python
algorithm_config = matching_engine_index_config.TreeAhConfig(
leaf_node_embedding_count=leaf_node_embedding_count,
leaf_nodes_to_search_percent=leaf_nodes_to_search_percent,
)
```

**After PR #5954**:
```python
algorithm_config = None
if (
leaf_node_embedding_count is not None
or leaf_nodes_to_search_percent is not None
):
algorithm_config = matching_engine_index_config.TreeAhConfig(
leaf_node_embedding_count=leaf_node_embedding_count,
leaf_nodes_to_search_percent=leaf_nodes_to_search_percent,
)
```

The `TreeAhConfig.as_dict()` method already handles `None` values correctly, so creating a `TreeAhConfig()` with default `None` values would generate valid JSON that the API accepts.

### Proposed Fix

Revert the conditional logic for `create_tree_ah_index()` to always create a `TreeAhConfig`:

```python
algorithm_config = matching_engine_index_config.TreeAhConfig(
leaf_node_embedding_count=leaf_node_embedding_count,
leaf_nodes_to_search_percent=leaf_nodes_to_search_percent,
)
```

### Workaround

Explicitly specify at least one of the optional parameters:

```python
index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
display_name="my-index",
dimensions=768,
approximate_neighbors_count=150,
distance_measure_type="DOT_PRODUCT_DISTANCE",
leaf_node_embedding_count=1000, # Explicitly specify default value
)
```

### Related

- PR #5954: "chore: Make MatchingEngineIndexConfig's algorithmConfig optional" (introduced this regression)
- Issue #2967: "MatchingEngineIndex create_tree_ah_index fails" (similar but different root cause, fixed in 1.36.4)

### Impact

Users following official Google tutorials and notebooks that don't specify `leaf_node_embedding_count` or `leaf_nodes_to_search_percent` will encounter this error.

### Next Steps

I am implementing a PR to fix this issue. I'll push it soon. The fix is straightforward - just revert the conditional logic in `create_tree_ah_index()` to always create a `TreeAhConfig`.

贡献指南

打开贡献指南

调研方向

从 matching_engine_index.py 中的 MatchingEngineIndex.create_tree_ah_index() 开始,检查 algorithm_config 的条件构造。验证 TreeAhConfig.as_dict() 如何序列化默认值 None,然后运行相关的现有 MatchingEngineIndex 测试。当不提供任一 leaf 参数的调用生成空的 treeAhConfig 而不是 null,并且被 API 接受时,即表示完成。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
api
Issue 类型
缺陷
难度
2/5
预计耗时
1-3 小时
活跃度
停滞
描述清晰度
描述清楚
新手友好度
35/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。