L-API tal-Embeddings: Mudelli u Dimensjonijiet
F'din il-paġna
Għanijiet
- Tmexxi s-sejħa
client.embeddings.create() - Tifhem id-differenzi bejn il-mudelli tal-embedding
- Tuża t-tnaqqis tad-dimensjonalità
Is-Sejħa Bażika
L-API sħiħa tal-Embeddings ta’ OpenAI tidħol f’metodu wieħed biss: client.embeddings.create(). Tgħaddilha stringa ta’ test u isem ta’ mudell:
from openai import OpenAI
client = OpenAI()
response = client.embeddings.create(
input="Hello, how are you?",
model="text-embedding-3-large"
)
embedding = response.data[0].embedding
print(f"Type: {type(embedding)}") # list
print(f"Length: {len(embedding)}") # 3072
print(f"Snippet: {embedding[:3]}") # [0.023, -0.041, 0.012]
L-oġġett li jirritorna mhux il-vettur innifsu iżda “wrapper” li fih vetturi multipli, għax l-API hija ddisinjata biex timmaniġġja lottijiet (batches). Ġewwa, issib data, lista ta’ oġġetti fejn kull wieħed għandu qasam embedding (il-vettur) u qasam index (il-pożizzjoni tiegħu fil-lott mibgħut); model, il-mudell attwali użat; u usage.prompt_tokens, in-numru ta’ tokens iffatturati. Għandek tirreġistra dan l-aħħar qasam mill-ewwel jum: hija l-unika kejl affidabbli ta’ kemm se tiswik l-indiċjar tiegħek.
Iż-Żewġ Mudelli Disponibbli
text-embedding-3-large huwa l-mudell b’prestazzjoni għolja. Id-3,072 dimensjoni tiegħu jaqbdu l-aktar sfumaturi semantiċi fini, u jagħmluh ideali għat-tfittxija f’korpusi kbar, pipelines RAG li jeħtieġu preċiżjoni, u ġeneralment kwalunkwe każ fejn il-preċiżjoni tiżen aktar mill-ispiża. Jekk utent jifformula mistoqsijiet b’mod indirett jew id-dokumenti tiegħek ikopru dominju tekniku dens, tara d-differenza fil-mod kif jiġu kklassifikati r-riżultati.
text-embedding-3-small huwa aktar kompatt b’1,536 dimensjoni u joffri proporzjon eċċellenti ta’ prezz għall-prestazzjoni. Huwa l-għażla t-tajba għall-klassifikazzjoni tat-test, ir-rakkomandazzjonijiet, il-prototipar rapidu, u applikazzjonijiet b’volum għoli fejn l-għan mhuwiex li tagħmel distinzjoni bejn żewġ dokumenti kważi identiċi iżda li tifred temi ċarament distinti. Ċiklu sempliċi jivverifika x’jirritorna kull wieħed:
# Compare the two models
for model_name in ["text-embedding-3-small", "text-embedding-3-large"]:
resp = client.embeddings.create(
input="Artificial intelligence",
model=model_name
)
vec = resp.data[0].embedding
print(f"{model_name}: {len(vec)} dimensions")
Embeddings f’Lottijiet (Batch)
Ma tindicijax korpus reali test wara test: kull sejħa HTTP tispiża round-trip tan-network, u l-ipproċessar ta’ elf dokument individwalment ifisser li takkumula elf dewmien (latency). L-API taċċetta sa 2,048 test f’sejħa waħda, u l-qasam index jippermettilek timmappja kull vettur lura għad-dokument korrett.
texts = [
"Machine learning is advancing rapidly",
"Deep learning is revolutionizing computer vision",
"Vector databases store embeddings",
"Python is the preferred language for data scientists"
]
response = client.embeddings.create(
input=textes,
model="text-embedding-3-large"
)
for item in response.data:
print(f"Text {item.index}: vector of {len(item.embedding)} dimensions")
print(f"Tokens consumed: {response.usage.prompt_tokens}")
Fil-prattika, agħmel gruppi tat-testijiet tiegħek f’lottijiet ta’ 100 sa 2,048 skont il-volum tiegħek: lottijiet iżgħar jagħmlu l-irkupru wara fallimenti aktar faċli, filwaqt li dawk akbar inaqqsu n-numru ta’ sejħiet. Immonitorja usage.prompt_tokens f’kull iterazzjoni biex tistma l-ispejjeż hekk kif timxi minflok ma tiskoprihom fil-kont finali, u implimenta tentattivi mill-ġdid (retries) b‘“exponential backoff”: qbiż tal-limitu tar-rata huwa żball tranżitorju, mhux raġuni biex tinterrampa xogħol ta’ indiċjar ta’ tliet sigħat.
Tnaqqis tad-Dimensjonalità
Il-mudelli text-embedding-3-* jaċċettaw parametru dimensions li jirritorna vetturi iqsar mid-daqs nattiv tagħhom:
# Full vector: 3072 dimensions
full = client.embeddings.create(
input="Reduction test",
model="text-embedding-3-large"
)
# Reduced vector: 256 dimensions
reduced = client.embeddings.create(
input="Reduction test",
model="text-embedding-3-large",
dimensions=256
)
print(f"Full: {len(full.data[0].embedding)} dim") # 3072
print(f"Reduced: {len(reduced.data[0].embedding)} dim") # 256
Il-mekkaniżmu huwa sempliċi: it-tnaqqis jaqta’ l-vettur u mbagħad jerġa’ jinnormalizzah. Peress li l-ewwel dimensjonijiet iġorru l-aktar informazzjoni, id-deterjorament jibqa’ gradwali ħafna. It-tabella hawn taħt tipprovdi parametri standard biex tippesa l-kwalità kontra l-ħażna.
| Dimensions | Relative Quality | Storage | Use Case |
|---|---|---|---|
| 3,072 | 100% | ~24 KB | High-precision search |
| 1,536 | ~98% | ~12 KB | Good general compromise |
| 512 | ~93% | ~4 KB | High volume, reduced cost |
| 256 | ~88% | ~2 KB | Prototyping, simple classification |
Ftakar li l-għażla tad-dimensjoni tiegħek torbotlek idejk: il-vetturi kollha f’indiċi partikolari għandu jkollhom l-istess daqs, u li tbiddel fehmek jeħtieġ li terġa’ tikkalkula kollox.
Ġestjoni tat-Tokens
Il-mudelli tal-embedding għandhom limitu massimu ta’ 8,191 token għal kull test, u l-API tirritorna żball jekk taqbeż dan. Huwa aħjar li tkejjel qabel ma tibgħat milli taqbad eċċezzjoni f’nofs lott:
import tiktoken
encoder = tiktoken.get_encoding("cl100k_base")
text = "A potentially long text..."
tokens = encoder.encode(text)
if len(tokens) > 8191:
# Truncate
truncated_text = encoder.decode(tokens[:8191])
print(f"Text truncated from {len(tokens)} to 8191 tokens")
It-trunkar huwa netwerk ta’ sigurtà, mhux strateġija: dokument twil imqatta’ jitlif it-tmiem tiegħu, u t-tmiem spiss ikun fih it-tweġiba li qed tfittex. L-immaniġġjar xieraq ta’ dokumenti kbar jinvolvi t-tqassim f’biċċiet (chunking), li se nkopru aktar tard fil-kors.
Punti Ewlenin
client.embeddings.create()jaċċetta test wieħed jew lista ta’ testi- Uża
text-embedding-3-large(3,072 dim) għall-preċiżjoni,text-embedding-3-small(1,536 dim) għall-effiċjenza tal-ispiża - Il-parametru
dimensionsjippermettilek tnaqqas id-daqs tal-vettur - Il-ħolqien ta’ lottijiet (batching) tat-testijiet huwa aktar effiċjenti minn sejħiet individwali
- Limitu ta’ 8,191 token għal kull test