Grimoire

Ghid pentru Venice Embeddings

4 min read

Ghid pentru Venice Embeddings

Ce face

venice-embeddings documentează apelarea endpoint-ului Venice pentru embeddings: POST /api/v1/embeddings.

Un embedding este o reprezentare numerică a unui text: un vector care păstrează aproximativ sensul. Texte apropiate semantic tind să aibă vectori apropiați. Asta permite căutare semantică, RAG, clustering, clasificare, deduplicare și reranking.

API-ul este compatibil cu stilul OpenAI pentru embeddings. Request-ul și response-ul sunt suficient de apropiate de https://api.openai.com/v1/embeddings încât SDK-ul OpenAI poate fi folosit cu baseURL: "https://api.venice.ai/api/v1".

Capabilitatea acoperă câmpurile principale din request: model, input, encoding_format, dimensions și user, plus compresie de response cu gzip sau br.

Vezi și All guides pentru restul ghidurilor.

Când îmi folosește

Folosește embeddings când aplicația trebuie să compare texte după sens, nu doar după potrivire exactă de cuvinte.

Exemple tipice:

  • retrieval sau RAG: cauți fragmente relevante într-o colecție de documente;
  • similarity search: găsești texte apropiate semantic;
  • clustering: grupezi documente asemănătoare;
  • clasificare, deduplicare sau reranking;
  • construirea unui index vectorial pentru căutare semantică.

Endpoint-ul este text-only în forma de bază. Pentru imagini sau semnale multimodale ai două opțiuni: treci imaginea printr-un vision chat model și embeduiești descrierea rezultată, sau alegi un model embedding multimodal din catalogul returnat de GET /models?type=embedding, după ce inspectezi model_spec.

Venice declară o poziție de no-training / no-retention pentru inputurile de inference, dar sursa nu publică semantică E2EE pentru /embeddings ca pentru unele modele chat. Nu promite criptare end-to-end unde nu este documentată. Un schelet mincinos tot schelet rămâne.

Cum îl invoc / declanșez

Nu există un trigger intern universal pentru toate instalările. Invocarea reală depinde de runtime-ul în care rulezi. Partea stabilă este endpoint-ul public și forma request-ului.

Request minim:

curl https://api.venice.ai/api/v1/embeddings \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Encoding: gzip, br" \
  -d '{
    "model": "text-embedding-bge-m3",
    "input": "Why is the sky blue?"
  }'

Schema de bază:

  • model: obligatoriu; model ID din GET /models?type=embedding;
  • input: obligatoriu; string, array de string-uri, number[] sau number[][] pentru input pre-tokenizat;
  • encoding_format: "float" implicit sau "base64" pentru payload mai mic;
  • dimensions: opțional; trunchiază dimensiunea outputului doar când modelul suportă asta;
  • user: acceptat pentru compatibilitate OpenAI, dar ignorat de Venice.

Cheia API se transmite ca Bearer token. Ține-o în variabile de mediu sau într-un secret manager. Nu o pune în cod, ghiduri, loguri sau exemple publice.

Exemplu practic

În TypeScript, cu SDK-ul OpenAI configurat pe Venice:

import OpenAI from 'openai'
 
const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: 'https://api.venice.ai/api/v1',
})
 
const res = await client.embeddings.create({
  model: 'text-embedding-bge-m3',
  input: ['first doc', 'second doc'],
})
 
const vec0 = res.data[0].embedding

Pentru batch-uri, trimiți mai multe texte în input. Venice returnează câte un embedding pentru fiecare element, în aceeași ordine, cu index corespunzător.

Modelul trebuie pin-uit. Distanțele cosine nu sunt comparabile între modele embedding diferite, deci nu amesteca vectori generați de modele diferite în aceeași colecție fără re-embedding.

Output / unde aterizează

Response-ul este un obiect de tip listă. Conține modelul folosit, array-ul data cu embeddings și usage cu tokenii consumați.

Exemplu de formă:

{
  "object": "list",
  "model": "text-embedding-bge-m3",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0023, -0.0093, 0.0158] }
  ],
  "usage": { "prompt_tokens": 8, "total_tokens": 8 }
}

Pentru batch-uri mari, cere compresie cu Accept-Encoding: gzip, br; response-ul va include Content-Encoding corespunzător. Vectorii sunt mari și payload-ul crește repede.

Dacă folosești x402 auth, header-ul X-Balance-Remaining raportează creditele USDC rămase.

Limite / gotchas

input nu poate fi gol. Venice respinge string-urile goale cu 400.

Array-urile batch sunt limitate la 2048 itemi. Fiecare string este limitat de model_spec.maxInputTokens, de obicei 8192, dar verifică per model în GET /models?type=embedding.

dimensions este sigur doar când model_spec.supportsCustomDimensions === true. Pe modele care nu suportă asta, comportamentul este dependent de model; testează întâi cu un request mic.

encoding_format: "base64" reduce payload-ul aproximativ de patru ori, dar trebuie decodat client-side.

Nu presupune că vectorii sunt L2-normalized. Verifică înainte cu o normă de tip Math.hypot(...v) ≈ 1.

Erori comune: 400 validation error, 401 auth sau model Pro-only, 402 balance insuficient, 415 Content-Type greșit, 429 rate limit, 500 inference failed și 503 model at capacity. La 429, folosește backoff exponențial și micșorează batch-ul.

Pentru RAG, stochează model lângă vector. Când schimbi modelul, re-embeduiești corpusul. Altfel compari oase de specii diferite și te miri că scheletul merge strâmb.

Graph View