Azure / Azure/azure-sdk-for-python

[Cosmos] [Embedding V0] Emulator tests + sample for embedding generation

Open
#46,736 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

# Emulator tests + sample for embedding generation

Parent: 46729
Depends on: 46733, 46734, 46735

## Goal

End-to-end smoke against the emulator (or a live Cosmos account once the gateway change ships) for a hybrid-search query that uses `embedding_generator`. Lives under `sdk/cosmos/azure-cosmos/tests/` and `sdk/cosmos/azure-cosmos/samples/`.

## Pre-requisite

**This issue cannot be fully exercised end-to-end until the gateway change is live** in either the emulator or a deployable backend, because Python has no `serviceinterop` fast path — it always asks the gateway for the query plan. The work itself can land behind the new feature flag (gated on `embedding_generator` being set) without breaking existing customers.

## Scope

1. Extend `tests/test_query_hybrid_search.py` and `tests/test_query_hybrid_search_async.py` with at least one case that:
- Issues a query expected to be rewritten with `embeddingParameterMap`.
- Passes a mock generator that returns deterministic vectors (e.g. `[float(i) for i in range(D)]`).
- Asserts the response is non-empty and the per-partition query was issued with the parameter populated. (One way: `mock_send_request` interception on the connection.)
- Skips with a clear message when the gateway version doesn't yet support `EmbeddingGeneration`.
2. New sample under `samples/`:
- `embedding_generation_sample.py` (sync)
- `embedding_generation_sample_async.py` (async)
- Shows how to implement an `EmbeddingGenerator` (a stub that returns `[0.0] * 1536` is fine for the sample), and how to pass it to `query_items`.
3. CHANGELOG entry under the current unreleased version, calling out:
- New `EmbeddingGenerator` / `AsyncEmbeddingGenerator` protocols.
- New `embedding_generator` keyword on `Container.query_items` / `ContainerProxy.query_items`.
- Dependency on the gateway change (link parent issue).

## Files touched

- `sdk/cosmos/azure-cosmos/tests/test_query_hybrid_search.py`
- `sdk/cosmos/azure-cosmos/tests/test_query_hybrid_search_async.py`
- `sdk/cosmos/azure-cosmos/samples/embedding_generation_sample.py` (new)
- `sdk/cosmos/azure-cosmos/samples/embedding_generation_sample_async.py` (new)
- `sdk/cosmos/azure-cosmos/CHANGELOG.md`

## Acceptance

- Emulator tests pass with a real or stubbed generator and document the gateway-version skip path.
- Samples run cleanly (or print "skipped: gateway support required" when not available).
- CHANGELOG entry is approved by the package's CODEOWNERS.

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.