Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

L-API tal-Embeddings: Mudelli u Dimensjonijiet

Lezzjoni 2 / 22 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Għanijiet
  2. Is-Sejħa Bażika
  3. Iż-Żewġ Mudelli Disponibbli
  4. Embeddings f’Lottijiet (Batch)
  5. Tnaqqis tad-Dimensjonalità
  6. Ġestjoni tat-Tokens
  7. Punti Ewlenin

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.

DimensionsRelative QualityStorageUse Case
3,072100%~24 KBHigh-precision search
1,536~98%~12 KBGood general compromise
512~93%~4 KBHigh volume, reduced cost
256~88%~2 KBPrototyping, 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 dimensions jippermettilek 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