Setting the file. One moment.
Subchapter 10.70
helpers/vector-contracts.mdMarkdown8 KBView on GitHub
File/Blob/ADLS; existing models only. No provisioning/catalogs/role changes/ installs/index repairs/cleanup. New unresolved intent: recommend hybrid; keyword-only skips this contract.
minimal is extraction, not retrieval mode. Lexical omits embeddingModel:
no source embedding model. Vectors and CU are independent choices for both
File/local uploads and Blob/ADLS containers; see the source matrix.
File --plan supports minimal and standard CU.
KB reasoning/answer
synthesis and agent tool use are separate; index verification proves neither.
File/ADLS: 2026-08-01-preview; Blob also 2026-04-01.
Set File vectorization: "azureOpenAI" or Blob processing: "minimal-vector" / "standard-cu";
add this closed embedding object to the owning procedure’s intent:
{"endpoint":"https://models.openai.azure.com","deployment":"embed","model":"text-embedding-3-large","dimensions":"service-managed","model_version":"deployment-managed","auth":"system-assigned","prerequisites":{"deployment":"<fresh selected deployment/model readback>","identity":"<Search managed identity and model role assignment readback>","network":"<approved model network reachability evidence>"}}All fields required; deployment is not a model family.
Models: text-embedding-ada-002, text-embedding-3-small,
text-embedding-3-large. HTTPS endpoints:
openai.azure.com, services.ai.azure.com, cognitiveservices.azure.com;
no keys, credentials, paths, query strings, explicit ports or APIM in this slice.
auth: system-assigned, using existing Search identity. Ingestion/query readbacks
allow only absent/null/empty-string apiKey and absent/null authIdentity.
Masked/nonempty/malformed keys or other identities block without echoing values.
Embedding guards preserve File CU’s MI or explicit ARM/ENV channel;
legacy modes remain.
Owner: read deployment/model and effective Search-to-model RBAC/network:
az cognitiveservices account deployment show --subscription <sub> --resource-group <group> --name <account> --deployment-name <deployment>
plus identity/role/network readbacks, not test embeddings. Record evidence
references: not independently verified by the planner. Missing evidence
blocks; refresh before approval.
Source guidance requires Cognitive Services User; the Azure OpenAI vectorizer also documents Cognitive Services OpenAI User. Policy owner verifies effective model data actions at that scope; never guess equivalence or assign roles.
Wire: embeddingModel.kind: azureOpenAI,
azureOpenAIParameters.resourceUri/deploymentId/modelName/authIdentity.
Neither API exposes dimensions or model-version pins: custom values block.
Observe generated dimensions: ada-002 requires 1536; 3-small allows 1–1536;
3-large allows 1–3072. Deployment upgrades remain owner-managed; Search readback
cannot pin or prove a model version.
Planners return planned, unapproved execution_input, hash-free
approval_summary of endpoint/deployment/auth/cost/data movement.
No model/query calls; inconsistent choices/definitions block.
Save only execution_input; apply via the owner’s --input after explicit
mutation/embedding-cost/data-transfer consent. Fresh exact reuse needs no
mutation approval/executor: not readiness or retrieval.
Retain artifact; use generated fields, never inferred names.
Use index-get or REST GET
/indexes('<index>')?api-version=<source-api> provides fields/profiles/vectorizers. Never modify or switch indexes.
python helpers/source_vector.py --plan verify.jsonFile:
{"schema_version":"1.0","source_plan_file":"source-execution.json","vector_field":"vector","content_field":"content","citation_field":"citation","expected_citation":"guide.txt","expected_text":"Example local data","query":"Where are examples?","mode":"vector","k":3,"not_before":null}mode: vector/hybrid; k: 1–10. Query/citation/text: nonempty,
at most 4096 characters. Three distinct simple field names; use actual schema
and corpus provenance, not illustrative names. No credentials/tokens.
Blob/ADLS not_before: explicit UTC synchronization start lower bound for this
ingestion, never an arbitrary old success. Redacted Storage bindings need paired
reuse_input_file/reuse_result_file creation receipts per the
Blob proof contract, loaded only when needed.
Checks: artifact/source/index identities/ETags, dimensions/profile/algorithm/vectorizer, endpoint/deployment/model/auth, retrievable content/citation/key. Unknown/redacted/ duplicate/conflicting metadata blocks. Permission sources/indexes require KB retrieval.
File: complete matching IDs/markers, no reported errors; uploads are synchronous. Blob/ADLS: bounded complete Storage/ACL observations; relevant completed nonempty cycle, zero failures/skips, no current cycle. Never start indexers. Zero-work: required proof. Stale/missing readiness blocks. Reread source/index; snapshots are not locks.
Exit 0: planned, configuration/ingestion observations, retrieval unverified,
unapproved execution_input, query/model/cost summary. Retain referenced artifacts;
keep private paths/fingerprints machine-only, never ask users to repeat hashes.
Save execution_input; explicitly approve query text, model calls/cost and
content transfer, then:
python helpers/source_vector.py --input approved-vector-query.jsonReobserve source, inventories/readiness and index; drift blocks before POST.
One vector-only request to the source-owned index:
POST /indexes('<index>')/docs/search.post.search?api-version=<source-api>,
vectorQueries: [{kind: text, text: <query>, fields: <vector-field>, k: <k>}],
top: k, minimumCoverage: 100, selected key/content/citation fields.
Hybrid additionally sends search, searchFields, queryType: simple in a
second request only after independent vector-only success. Never fall back
to lexical retrieval. No KB/chat/semantic answers.
Require HTTP 200/request ID, full coverage, nonempty bounded unique hits, finite
scores, matching expected citation and content. Partial/error/continuation/
malformed/mismatched responses block. Reobserve afterward and reject drift.
retrieval-verified: this runtime probe passed, not corpus-wide quality.
Evidence: request IDs/digests/counts, not raw documents/citations.
Tests/mocks are never cloud evidence.
Blocked queries: exit 2, zero resource writes, attempted count/possible billing;
no ambiguous-query retries. Source writes retain partial/separate cleanup.
After definition/model/identity/policy/data drift, rerun source/verification
--plan, replace artifacts and discard consent.
Bounds: each observation uses existing File limits (200 pages/records, 60-second listing budget, 1 MiB/page) or the source artifact’s complete Blob/ADLS discovery limits. It adds four Search definition/index GETs and, for Blob, one status GET. One planning observation; two bracket approved queries. At most two query POSTs, each capped at 8 MiB and a 60-second body-read budget; added GETs use the same caps. Overflow blocks. No redirects or unbounded background work. Body budgets are not hard DNS/connect/header/scheduling deadlines.
Authorities: failure/conflict/uncertainty only.