Azure / Azure/azure-sdk-for-python
[Cosmos] [Embedding V0] Emulator tests + sample for embedding generation
- 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
Assessment
This issue has not been assessed yet.