Eqa uye okuqukethwe
Ukuphathwa kwamaphutha

Ukuphathwa kwamaphutha

Isicelo esihlulekayo sibuyisela ikhodi yesimo se-HTTP nomzimba we-JSON onohlobo lwephutha nomlayezo. Leli khasi libala zonke izimo, libonisa umzimba wephutha wefomethi ngayinye ye-API futhi lithi yimaphi amaphutha afanele ukuthunyelwa futhi.

Ama-SDK adala into yephutha ephethe ikhodi yesimo nama-field omzimba. Lesi sicelo siqamba i-model engekho:

import openai
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

try:
    client.chat.completions.create(
        model="no-such-model",
        messages=[{"role": "user", "content": "Hello"}],
    )
except openai.APIStatusError as error:
    print(error.status_code)                           # 400
    print(error.type)                                  # invalid_request_error
    print(error.body["message"])                       # unknown model: no-such-model
    print(error.response.headers.get("x-request-id"))  # the id of this request

Sibuyisela isimo 400 nalo mzimba:

400 JSON
{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}

Umzimba wephutha

Kunemizimba emibili. I-/v1/messages iphendula ngefomethi ye-Anthropic; wonke amanye ama-endpoint aphendula ngefomethi ye-OpenAI. Kuzo zombili, imininingwane ikuyi-error.type ne-error.message, ngakho umfundi oyedwa usebenza kuwo wonke ama-endpoint.

401 Ifomethi ye-OpenAI
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Ifomethi ye-Anthropic
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}
I-field Uhlobo Incazelo
error.type string Uhlobo lwephutha. Bheka Izinhlobo zamaphutha ngezansi.
error.message string Umusho wabantu. Imibhalo emathebuleni angezansi izinzile ngaphandle kwezingxenye zayo eziguquguqukayo, ezibonisiwe njenge-<id>, <n> noma ….
error.code string | null Ikhona kwamanye amaphutha efomethi ye-OpenAI: i-invalid_api_key ne-401, i-request_too_large ne-413, i-context_length_exceeded uma ingxoxo mide kakhulu, kungenjalo i-null noma ayikho. Nquma kuqala ngesimo ne-error.type bese uthatha i-code njengesengezo.
error.param null Ikhona emaphutheni afanayo ne-code. Njalo null.
type string Ifomethi ye-Anthropic kuphela. Njalo error.

Izinhlobo zamaphutha

Uhlobo Izimo Incazelo
invalid_request_error 400, 413, 415, 422 Isicelo ngokwaso asilungile: i-field, umzimba, i-id ye-model noma okufakwayo i-model engakwamukeli. Shintsha isicelo ngaphambi kokusithumela futhi.
authentication_error 401 I-API key ilahlekile, ayaziwa noma ihoxisiwe.
not_found_error 404 Indlela ayikho.
rate_limit_error 429 I-balance ayilaleli isicelo, i-flood protection isimisile, noma i-model iyatshwa. Umlayezo usho ukuthi yiliphi.
api_error 500, 502, 503, 504 Isicelo besilungile futhi ukwehluleka kohlangothini lwethu. Sithumele futhi.
server_error 500 Isicelo besilungile futhi ukwehluleka kohlangothini lwethu. Sithumele futhi.

Amakhodi esimo

Isimo Uhlobo Umlayezo Nini
400 invalid_request_error Failed to parse the request body as JSON: … Umzimba awuyona i-JSON evumelekile.
400 invalid_request_error unknown model: <id> I-model akuyona i-id eshicilelwe. Ku-/v1/responses nalapho i-model ilahlekile.
400 invalid_request_error No user message provided Amazinga e-Shannon: isicelo asiphethe mbhalo womsebenzisi.
400 invalid_request_error <id> does not accept image input Isithombe sithunyelwe ku-model ye-open-weight ehlinzekiwe engenakho ukufakwa kwezithombe.
400 invalid_request_error audio and video input are not supported by any hosted model Ingxenye yomsindo noma yevidiyo ithunyelwe ku-model ye-open-weight ehlinzekiwe.
400 invalid_request_error <id> does not accept response_format Okuphumayo okuhleliwe kucelwe ku-model ye-open-weight ehlinzekiwe engenakho.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object I-JSON schema ithunyelwe ku-model ye-open-weight ehlinzekiwe eyamukela i-json_object kuphela.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Umzamo wokucabanga akusilo elinye lamanani abaliwe. Ama-model e-open-weight ahlinzekiwe.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Ukubalwa kwama-token kucelwe ku-model engaphandle kwama-model e-open-weight ahlinzekiwe.
401 authentication_error Missing authentication Ayikho i-API key ethunyelwe.
401 authentication_error Invalid API key I-key ayaziwa, ishintshelwe eyisha, noma ihoxisiwe.
404 not_found_error Not Found Indlela ayikho, isibonelo /v1/embeddings.
405 api_error Method Not Allowed Indlela ikhona kodwa hhayi nale ndlela ye-HTTP.
413 invalid_request_error Failed to buffer the request body: … Umzimba wesicelo mkhulu kuno-32 MiB.
415 invalid_request_error Expected request with `Content-Type: application/json` I-header ye-Content-Type ilahlekile noma ayiyona i-application/json.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … I-field edingekayo ilahlekile, njenge-messages, noma i-field inohlobo olungalungile lwe-JSON.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan Umkhawulo wokuphumayo wesicelo mkhulu kunalokho okusele ku-balance yakho.
429 rate_limit_error Too many requests. Retry in <n>s. I-flood protection: izicelo ezingaphezu kwe-120 ngomzuzu owodwa ku-akhawunti yakho. I-<n> yinani lemizuzwana kuze kuphele umzuzu.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan I-shannon-coder-1 ku-/v1/chat/completions na-/v1/messages: izicelo ze-Shannon Coder zepulani yakho zewindi lamahora angu-4 lamanje sezisetshenzisiwe.
429 rate_limit_error Shannon routes are temporarily busy. Please retry. I-model iyatshwa kulo mzuzu.
500 server_error The model backend failed to answer. Please retry. I-model ayikhiqizanga mpendulo.
500 server_error An internal error occurred. Please retry. Ukwehluleka kwangaphakathi ngenkathi isicelo silungiselelwa.
502 api_error The model backend failed to answer. Please retry. I-model ayikhiqizanga mpendulo. Umndeni we-Shannon 3 nama-model e-open-weight ahlinzekiwe.
503 api_error Could not verify your quota right now. Please retry. I-balance yakho ayikwazanga ukufundwa kulo mzuzu.
503 api_error token counting is temporarily unavailable for this model Ukubalwa kwama-token akutholakali kule model kulo mzuzu.
504 api_error upstream timed out I-model ye-open-weight ehlinzekiwe ithathe isikhathi eside kunomkhawulo wesikhathi wesicelo esingasakazwa.

Ukuhlola kwenziwa ngalolu hlelo: i-API key, umzimba wesicelo, i-id ye-model, i-flood protection, i-balance. Isicelo esine-key engalungile nomzimba ongalungile ngakho sibuyisela i-401. Isicelo esinqatshwa ngesimo se-4xx asibiziswa.

I-balance ne-flood protection

Isicelo ngasinye sisetshenziswa ngokulinganayo: awekho amazinga omkhawulo wezinga futhi akukho ikhwota ye-API ehlukile. Izinto ezimbili zisengaphendula nge-429, zombili ngohlobo rate_limit_error. Umlayezo uzihlukanisa.

I-balance

I-balance yakho iyi-allowance yepulani yanamuhla, esha ngo-00:00 UTC, nangemva kwayo i-credit yakho ethengiwe. Ingxoxo ne-API zisebenzisa i-balance efanayo.

Isicelo ngasinye siqala ngokubeka eceleni umkhawulo waso wokuphumayo: i-max_tokens, noma i-max_output_tokens ku-/v1/responses, 4,096 uma ungathumeli lutho. Uma impendulo isiphelele, inani elibekelwe eceleni lifakwa esikhundleni salokho isicelo esikusebenzisile. Uma inani lingangeni ku-balance esele, isicelo sibuyisela Quota exceeded ngaphambi kokuba i-model iqale.

Izicelo ezisebenza ngesikhathi esisodwa ngasinye sibeka eceleni inani laso. Izicelo eziningi ezifanayo ezine-max_tokens ephezulu zingasebenzisa i-balance okwesikhashana, noma impendulo ngayinye imfushane. I-max_tokens ephansi ibeka eceleni okuncane.

I-flood protection

I-flood protection ivumela izicelo ezingu-120 ngomzuzu nge-akhawunti. Ibala i-akhawunti, hhayi i-key, kuma-/v1/chat/completions, /v1/responses na-/v1/messages ndawonye. Umzuzu uqala ngesicelo sakho sokuqala.

Isicelo inombolo 121 phakathi kwaleso mzuzu sibuyisela Too many requests. Retry in <n>s. futhi asibizi lutho. Izicelo ezinqatshiwe nazo ziyabalwa, ngakho iklayenti elithumela futhi ngaphandle kokulinda lihlala linqatshwa kuze kuphele umzuzu. Linda imizuzwana engu-<n> evela emlayezweni.

Izicelo ezithunyelwe ngokufana azinqatshwa ngenxa yokuba zifana. Zilinda emgqeni bese ziphendulwa ngokulandelana.

I-GET /v1/models nama-endpoint okubala ama-token awabalwa.

Okwengeziwe ngemikhawulo ne-balance, nalapho ubona khona i-balance nokusetshenziswa kwakho: Imikhawulo ne-balance Ama-key nokusetshenziswa

Okufanele kuzanywe futhi

Thumela isicelo futhi kuphela uma isicelo esifanayo singaphumelela. Ama-OpenAI ne-Anthropic SDK asevele azama futhi izimpendulo ze-429 ne-5xx kabili ngokwawo; setha i-max_retries (maxRetries ku-JavaScript) ukuze ushintshe lokho.

Iphutha Thumela futhi? Kanjani
400, 404, 405, 413, 415, 422 Cha. Lungisa isicelo kuqala. Umlayezo uqamba i-field, i-model noma okufakwayo okungalungile.
401 Cha. Sebenzisa i-key evumelekile. Dala noma shintsha i-key ekhasini le-Ama-key nokusetshenziswa.
429 Too many requests Yebo, ngemva kokulinda. Linda inani lemizuzwana elisemlayezweni, bese uthumela isicelo esifanayo.
429 Quota exceeded Hhayi njengoba injalo. Yehlisa i-max_tokens, linda ukusha kwansuku zonke ngo-00:00 UTC, noma engeza i-credit.
429 Shannon Coder call quota reached Yebo, kwiwindi elilandelayo. Amawindi aqala njalo emahoreni angu-4 kusukela ngo-00:00 UTC. I-model enye iphendula ngokushesha.
429 … temporarily busy Yebo. Linda imizuzwana embalwa, bese ulinda isikhathi eside ngemizamo elandelayo.
500, 502, 503 Yebo. Linda umzuzwana o-1, bese u-2, u-4 no-8. Yeka ngemva kwemizamo embalwa bese ubika i-id yesicelo.
504 Yebo. Yithumele nge-stream esethelwe ku-true: umkhawulo wesikhathi usebenza ezimpendulweni ezingasakazwa.

Isiyingi sokuzama futhi esilandela leli thebula:

import re
import time

import openai
from openai import OpenAI

# max_retries=0: this loop does the retrying, the SDK does not add its own.
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1", max_retries=0)


def create_with_retry(attempts=5, **request):
    for attempt in range(attempts):
        try:
            return client.chat.completions.create(**request)
        except openai.RateLimitError as error:
            text = str(error)
            flood = re.search(r"Retry in (\d+)s", text)
            if flood:
                time.sleep(int(flood.group(1)))   # flood protection: wait out the minute
            elif "temporarily busy" in text:
                time.sleep(2 ** attempt)
            else:
                raise                             # balance: a wait of seconds does not help
        except (openai.InternalServerError, openai.APIConnectionError):
            time.sleep(2 ** attempt)              # 1, 2, 4, 8 seconds
    raise RuntimeError("the request failed after all attempts")


response = create_with_retry(
    model="shannon-3",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

Amaphutha ngaphakathi kwe-stream

I-stream inesimo 200 kusukela ku-byte yayo yokuqala. Ukwehluleka ngemva kwalokho kufika njengomcimbi ngaphakathi kwe-stream: i-chunk enelungu le-error ku-/v1/chat/completions, umcimbi we-error ku-/v1/messages, umcimbi we-response.failed noma we-error ku-/v1/responses. Imicimbi yokuvala ye-stream isalandela. Thatha impendulo enjalo njengehlulekile bese uthumela isicelo futhi, njengasesimeni se-5xx.

Ingxoxo ende kunewindi lomongo le-model ibikwa ngale ndlela, ngohlobo invalid_request_error nekhodi context_length_exceeded. Finyeza ingxoxo ngaphambi kokuthumela futhi.

Ama-frame aqondile achazwe nge-streaming. Ukusakaza

Ama-id ezicelo

Yonke impendulo, kufaka amaphutha, inayo i-header ye-x-request-id. Liyinani olithumele ku-header yakho ye-x-request-id, noma izinhlamvu ze-hexadecimal ezingu-12 uma ungathumelanga lutho. Yirekhode, futhi yicaphune uma ucela usizo ngesicelo.