/v2/chat ning lisada vastavalt rakenduse vajadustele Embed-, Rerank-, Parse- või partiitöötluse API-d. Selles juhendis selgitatakse, kuidas juurdepääs toimib, kuidas teha esimene päring ja mida tuleks arvesse võtta enne proovivõtmelt tootmiskeskkonda üleminekut.
Mis on Cohere API ja millal seda kasutada?
Cohere API on arendajatele mõeldud platvorm, mille abil saab rakendustesse lisada keele genereerimise, semantilise otsingu ja dokumentide analüüsi võimalused. Selle praegune generatiivne liides on Chat API v2, mis kasutab järjestatud messages massiivi, mis võib sisaldada süsteemi-, kasutaja-, assistendi- ja tööriistasõnumeid. See on mõeldud rakendustele, mitte igapäevaseks tarbijatele suunatud vestlemiseks.
Platvorm on eriti asjakohane siis, kui rakendus vajab ettevõtteotsingut, otsinguga täiendatud genereerimist (RAG), mitmekeelseid vastuseid, dokumentide analüüsi, tööriistapõhiseid töövooge või juurutamise juhtelemente, näiteks privaatset taristut, Model Vaulti või pilveteenuse pakkujate integratsioone. RAG tähendab asjakohase teabe hankimist ühendatud andmeallikast ja selle edastamist mudelile kontekstina enne vastuse genereerimist.
Cohere ei ole kõige loomulikum valik tarbijatele mõeldud vestlusroboti, piltide või videote genereerimise toote ega üldotstarbelise isikliku assistendi jaoks. Selle API-d pakuvad ehitusplokke, kuid kasutajaliideste, andmetorude, tööriistade käivitamise, õiguste ja suurema osa töövoogude korraldamise eest vastutab endiselt teie rakendus.
Kuidas saada juurdepääs ja API-võti?
Looge Cohere'i konto ja hankige Cohere'i arendajate juhtpaneeli kaudu prooviperioodi API-võti. Võti autentib päringuid HTTP Authorization: Bearer päise abil. Salvestage võti keskkonnamuutujasse, mitte otse lähtekoodi või brauserirakendusse.
Proovivõtmed on mõeldud arenduseks ja nende kasutusele kehtivad päringupiirangud. Esitatud platvormiteabe kohaselt on proovikasutus piiratud ning see ei sobi tootmis- ega äriliseks kasutuseks. Tootmiskasutuseks tuleb Cohere'i konto- ja arveldusvoo kaudu üle minna tasulisele kasutusele.
export COHERE_API_KEY="your-api-key"Juhtpaneel pakub ka mänguvälja päringute interaktiivseks proovimiseks: dashboard.cohere.com/playground. Kasutage seda mudeli käitumise ja päringuvormingute uurimiseks enne rakenduse koodi kirjutamist, kuid testige autentimist, veakäsitlust ja päringupiirangute käitumist ka oma integratsioonis.
Millise Cohere'i API ja mudeli peaksite valima?
Valige API vastavalt ülesandele, mitte ärge käsitlege Chati ainsa liidesena:
- Chat API v2: vestluspõhine genereerimine, RAG, viited, voogedastus, tööriistade kutsumine, struktureeritud väljund ja ühilduvad pildisisendid.
- Embed API: teisendab teksti või toetatud pildid vektoriteks, mida saab kasutada semantilises otsingus, klassifitseerimisel ja otsingul.
- Rerank API: järjestab otsingutulemused või leitud dokumendid asjakohasuse järgi ümber, enne kui need edastatakse generatiivsele mudelile.
- Parse API: teisendab toetatud dokumendid ja pildid edasiseks töötlemiseks mõeldud Markdowniks või struktureeritud plokkideks.
- Datasets ja Embed Jobs: võimaldavad suuremate andmekogumite failipõhiseid asünkroonseid vektoriseerimise töövooge.
- Batch API: töötleb üles laaditud päringuandmekogumeid toetatud töökoormuste korral asünkroonselt.
Mudelite ühilduvus sõltub võimalustest. Valige aktiivne mudel, mis toetab vajalikke funktsioone, näiteks tööriistu, struktureeritud väljundit või pildisisendit, ning kontrollige enne juurutamist kehtivat mudelidokumentatsiooni. Pärandgenereerimise lõpp-punkte ja vanemaid mudelialiasid ei tohiks uutes integratsioonides kasutada.
Kuidas teha esimene päring?
REST-i baasaadress on https://api.cohere.com. Järgmine päring kasutab Chat API v2. Vajaduse korral asendage näites olev mudeli identifikaator teie kontol saadaval oleva aktiivse mudeliga.
curl --fail-with-body --silent --show-error https://api.cohere.com/v2/chat
-H "Authorization: Bearer ${COHERE_API_KEY}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '{
"model": "command-a-plus-05-2026",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain retrieval-augmented generation in two sentences."}
]
}'Sama päringu saab teha Cohere'i praeguse Pythoni SDK-ga. Installige pakett käsuga pip install -U cohere ja kasutage v2 klienti.
import os
import cohere
client = cohere.ClientV2(api_key=os.environ["COHERE_API_KEY"])
response = client.chat(
model="command-a-plus-05-2026",
messages=[
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain semantic search in two sentences."}
],
)
text = "".join(
part.text for part in response.message.content
if part.type == "text"
)
print(text)Kuidas vastust lugeda?
Chat API v2 vastus sisaldab sisuosadega sõnumit. Tekstisisu esitatakse sisuosana, mille tüüp on text. Rakendused peaksid tekstiosad kokku koguma, mitte eeldama, et vastus on alati üks lihtne string, sest sõltuvalt päringust võib vastus sisaldada ka tööriistakutseid, viiteid või muud tüüpi sündmusi.
Tootmiskoodis käsitlege ebaõnnestunud HTTP-vastuseid, tühja või ootamatut sisu, päringupiirangu vastuseid ja mudelispetsiifilisi vigu. Säilitage võimaluse korral kasutusmetaandmed, et rakendus saaks mõõta tokenite kasutust ning uurida kulude või latentsuse muutusi.
Kuidas Cohere API hinnastamine toimib?
Cohere kasutab kasutuspõhist hinnastamist, mis sõltub mudelist ja lõpp-punktist. Generatiivsete mudelite hinda arvestatakse üldjuhul sisend- ja väljundtokenite põhjal. Ümberjärjestamise hinda arvestatakse otsingumahu või kohaldatavate ühikute järgi, vektoriseerimise hinda aga vektoriseeritud tokenite või töökoormusühikute alusel. Spetsiaalsetel või hallatud juurutusvõimalustel on eraldi hinnastamine.
Proovivõtmed on tasuta, kuid nende kasutusele kehtivad päringupiirangud. Esitatud piiranguteabe kohaselt on proovivõtmed üldjuhul piiratud 1000 API-kõnega kuus ja Chat-mudelite puhul tavaliselt 20 päringuga minutis. Tootmispiirangud sõltuvad mudelist ja lõpp-punktist; esitatud dokumentatsiooni näidete kohaselt võib mitmel aktiivsel Chat-mudelil piir olla kuni 500 päringut minutis, Embedi puhul 2000 sisendit minutis ja Reranki puhul 1000 päringut minutis. Mõne uuema mudeli tootmispiirangute saamiseks tuleb müügiosakonnaga ühendust võtta.
Enne kulude hindamist kontrollige Cohere'i kehtivat hinnastamis- ja päringupiirangute dokumentatsiooni. Ärge eeldage, et ühe mudeli piirang või hind kehtib ka teisele.
Mida saavad arendajad API abil luua?
Voogedastatavad vastused
Chati vastuseid saab voogedastada serveri saadetud sündmustena. Selle asemel et oodata täielikku vastust, saab rakendus sündmusi sisu genereerimise ajal. See on kasulik kasutajaliidestes, kus esimeste sõnade kiire kuvamine on oluline. Voosündmused võivad sisaldada sõnumi algust, sisudeltasid, tööriistakutseid, viiteid ja lõpetamissündmusi.
stream = client.chat_stream(
model="command-a-plus-05-2026",
messages=[
{"role": "user", "content": "Explain embeddings in three short steps."}
],
)
for event in stream:
if event.type == "content-delta" and event.delta and event.delta.message:
print(event.delta.message, end="", flush=True)
print()Vektoriseerimine, ümberjärjestamine ja RAG
Tüüpiline RAG-torustik kasutab Embedi dokumentide ja kasutajapäringute vektoritena esitamiseks, otsingusüsteemi kandidaattekstide leidmiseks ning Reranki nende kandidaatide järjestuse parandamiseks. Seejärel edastatakse valitud tekstilõigud Chatile kontekstina. Nii eraldatakse otsing genereerimisest ja rakendus saab kontrollida, millist ettevõttesisest teavet mudelile näidatakse.
Cohere toetab Chati töövoogudes ka viiteid ja otsingudokumente. Rakendus peab enne leitud sisu mudelile saatmist siiski juurdepääsuõigusi kontrollima.
Tööriistade ja funktsioonide kutsumine
Tööriistad võimaldavad mudelil taotleda tegevust, näiteks ettevõttesisese süsteemi päringut või tellimuse andmete vaatamist. Mudel ise tööriista ei käivita. Rakendus saab tööriistakutse, valideerib taotletud argumendid, teeb toimingu ja saadab tulemuse jätkusõnumiga tagasi.
Tööriistade määratlused kasutavad JSON Schema laadset kirjeldust. Cohere toetab mitmeastmelisi ja paralleelseid tööriistamustreid, kuid rakendus vastutab endiselt autoriseerimise, valideerimise, korduskatsete, ajalõppude ja ohtlike toimingute ennetamise eest. Eksperimentaalne strict_tools valik saab ühilduvates Chat API v2 töövoogudes jõustada tööriistade nimed, kohustuslikud parameetrid ja parameetrite tüübid.
Struktureeritud väljundid
Chat API v2 toetab ühilduvatel mudelitel parameetrit response_format JSON-režiimi ja JSON Schema laadse väljundi jaoks. Näiteks:
response = client.chat(
model="command-a-plus-05-2026",
messages=[
{"role": "user", "content": "Describe semantic search with fields name and benefit."}
],
response_format={"type": "json_object"},
)
print(response.message.content[0].text)JSON-režiim ei kaota vajadust tulemust valideerida. Mudelite ühilduvus varieerub ning struktureeritud väljundit tuleks käsitleda vastuse vormingu funktsioonina, mitte eraldi ainult JSON-i toetava API-na.
Pildid, dokumendid ja failid
Ühilduvad nägemismudelid aktsepteerivad pilte HTTP-URL-ide või base64-andme-URL-ide kaudu. Toetatud pildivormingud hõlmavad PNG-d, JPEG-i, WEBP-d ja animeerimata GIF-i, arvestades dokumenteeritud piltide arvu ja päringu suuruse piiranguid.
Cohere toetab manustamistööde jaoks ka CSV- ja JSONL-andmekogumite üleslaadimist ning pakub Parse API kaudu dokumentide ja piltide parsimist. Need üleslaadimised on ülesandepõhised; need ei ole universaalne püsiv failiotsinguhoidla. Andmekogumifailid kustutatakse automaatselt pärast dokumenteeritud 30-päevast säilitamisperioodi, välja arvatud juhul, kui need kustutatakse varem.
Millised SDK-d ja arendajatööriistad on saadaval?
Cohere toetab ametlikult Pythoni, TypeScripti, Java ja Go SDK-sid. REST-i ja HTTP-ühendust saab kasutada ka teistest keeltest, sealhulgas PHP-st. Praegune Pythoni klient kasutab cohere.ClientV2; praegune TypeScripti pakett kasutab CohereClientV2 paketist cohere-ai.
Kasutage koos ametlikku API viitejuhendit, mudelidokumentatsiooni, SDK hoidlaid, mänguvälja, näidiskogumikke ja aegumise teateid. Mänguväli on kasulik avastamiseks, samas kui automatiseeritud testid peaksid kontrollima täpseid päringu- ja vastusestruktuure, millest teie rakendus sõltub.
Millised piirangud ja tootmiskasutuse probleemid on olulised?
- Päringupiirangud: Piirangud erinevad proovivõtmete ja tootmisvõtmete ning mudelite ja lõpp-punktide vahel. Rakendage viivituse suurendamist ja käsitlege piirangute vastuseid.
- Latentsus: Ühtset universaalset latentsusgarantiid ei ole. Vastamisaega mõjutavad mudeli valik, viiba suurus, väljundi pikkus, pildi detailsus, tööriistad, järjekorra prioriteet ja juurutus. Voogedastus võib tajutavat ooteaega vähendada.
- Mudeli ühilduvus: Tööriistad, struktureeritud väljund ja pildisisend ei pruugi olla saadaval igas mudelis. Testige iga võimalust valitud mudeliga.
- Andmete säilitamine: Säilitamine sõltub tootest ja juurutusest. Model Vault võib toetada nullandmesäilituse konfiguratsioone, samas kui privaatsed ja partnerpilve juurutused võivad pakkuda tugevamat kliendi kontrolli all olevat andmepiiri.
- Turvalisus: Hoidke API-võtmeid serveripoolselt, valideerige tööriistade argumendid, filtreerige leitud sisu ja rakendage rakendustaseme autoriseerimist enne ettevõtteandmetele või -toimingutele juurdepääsu võimaldamist.
- Aegumised: Pärandlõpp-punkte, näiteks
/v1/generate,/v1/summarizeja/v1/classify, ning nendega seotud pärandfunktsioone ei tohiks uute rakenduste aluseks võtta. - Peenhäälestus: Cohere'i aegumisdokumentatsiooni kohaselt lõpetati loetletud platvormi peenhäälestusvõimaluste kasutuselevõtt 15. septembril 2025. Ärge kavandage uut integratsiooni ajalooliste peenhäälestuse lõpp-punktide ümber.
Kas Cohere API on teie projekti jaoks hea valik?
Cohere on tugev kandidaat, kui organisatsioon vajab mitmekeelset genereerimist, semantilist otsingut, ümberjärjestamist, dokumentide töötlemist, agendipõhiseid töövooge või juurutusvõimalusi, mis hõlmavad privaatseid, spetsiaalseid, pilve- või internetiühenduseta keskkondi. Chati, Embedi, Reranki ja Parse'i eraldatus on kasulik kontrollitud ettevõtteotsingu ja RAG-süsteemide loomisel.
See võib olla halb valik, kui peamine nõue on tasuta tarbijatele mõeldud vestlusrobot, esimese osapoole mobiili- või töölauarakendused, piltide või videote genereerimine või täielikult hallatud isikliku produktiivsuse ökosüsteem. Ettevõtete hinnastamine on sageli kohandatud, keerukamad töövood nõuavad rakendusepoolset arendust ning võimalused võivad mudeli ja juurutuse järgi erineda. Hinnake kogu töövoogu, sealhulgas andmehaldust, otsingu kvaliteeti, kasutuspiiranguid ja tööriistade turvalisust, mitte üksnes tekstigeneratsiooni.
