Azure / Azure/azure-sdk-for-python

[Cosmos] [Embedding V0] _resolve_embeddings helper on hybrid-search aggregator (sync + async)

Open
#46,732 0 comments 0 reactions 0 assignees View on GitHub
Cosmos feature-request
Dominant language
Python
Stars
5.6k
Forks
3.4k
Avg merge
1d 21h
Merged PRs (30d)
193

Description

# Embedding-resolution helper on the hybrid-search aggregator (sync + async)

Parent: 46729
Depends on: 46730, 46731

## Goal

Add a single helper that takes the `embeddingParameterMap` from the plan, calls the customer-provided generator once with the full batch, and returns the augmented parameter list. No mutation of caller state.

## Scope

Add (sync) on `_HybridSearchContextAggregator`:

```python
def _resolve_embeddings(self):
embedding_map = self._partitioned_query_ex_info.get_embedding_parameter_map()
if not embedding_map:
return
generator = self._options.get("embeddingGenerator")
if generator is None:
raise ValueError(
"Query requires embedding generation but no embedding_generator "
"was passed to query_items."
)
keys, texts = zip(*sorted(embedding_map.items())) # stable order
vectors = generator.generate_embeddings(list(texts))
if len(vectors) != len(texts):
raise ValueError(
f"embedding_generator returned {len(vectors)} vectors for {len(texts)} texts"
)
for i, v in enumerate(vectors):
if v is None:
raise ValueError(f"embedding_generator returned a null vector at index {i}")
extra = [{"name": k, "value": list(v)} for k, v in zip(keys, vectors)]
base = list(self._parameters or [])
self._parameters = base + extra
```

Mirror in `aio/hybrid_search_aggregator.py`:

```python
async def _resolve_embeddings_async(self):
...
vectors = await generator.generate_embeddings_async(list(texts))
...
```

Add a type guard at the async entry point: if a sync `EmbeddingGenerator` is passed (no `generate_embeddings_async`), raise `TypeError` early with an actionable message.

## Non-goals

- Do NOT yet call this from `_run_hybrid_search`; that lives in 46733.
- Do NOT add the diagnostics span here; that lives in 46734 (but the call-site for the span will be inside this helper).

## Files touched

- `sdk/cosmos/azure-cosmos/azure/cosmos/_execution_context/hybrid_search_aggregator.py`
- `sdk/cosmos/azure-cosmos/azure/cosmos/_execution_context/aio/hybrid_search_aggregator.py`

## Acceptance

- Helper is non-mutating for the no-op case (no map → no parameter changes).
- Sort-stable (same map → same parameter order).
- Raises `ValueError` with clear messages on cardinality mismatch / null entry / missing generator.
- Async path raises `TypeError` if a sync generator is passed.
- 100 % unit-test coverage of the helper (covered by 46735).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.