Kimi API Platform

Mis on Kimi API platvorm?

Kimi API platvorm, mida nimetatakse ka Kimi Open Platformiks, võimaldab tarkvararakendustel saata päringuid Moonshot AI Kimi mudelitele ja saada genereeritud vastuseid. API ehk rakendusliides on struktureeritud viis, kuidas üks programm saab teiselt teenuselt toimingut paluda. Selle asemel et kasutada Kimit brauseri või mobiilirakenduse kaudu, kasutavad arendajad oma rakendustes HTTP-päringuid või SDK-d.

Peamine teenuse URL on https://api.moonshot.ai. Platvorm pakub OpenAI-ga ühilduvaid Chat Completionsi ja Responsesi API-sid, Anthropicuga ühilduvat Messagesi API-t, failide lõpp-punkte, veebiotsingu tööriistu, URL-ide sisu hankimist ja pakktöötlust. Uue OpenAI-laadse integratsiooni korral soovitab ajakohane dokumentatsioon kasutada praegust Kimi mudelit, näiteks mudelit kimi-k3, OpenAI-ga ühilduva API kaudu.

API sobib arendajatele, kes vajavad pika kontekstiga teksti genereerimist, programmeerimisabi, dokumentide analüüsi, visuaalset mõistmist, uurimistöövooge, struktureeritud vastuseid või rakendusi, mis saavad kutsuda väliseid tööriistu. See sobib halvemini olukordades, kus organisatsioon vajab tavapärase API-liikluse kohta täielikult dokumenteeritud treenimisest loobumise garantiid, kontotasemest sõltumatuid ja väga ettearvatavaid limiite või piirkondlikke andmekäitluse tingimusi, mida ei ole lepinguliselt kinnitatud.

Juurdepääsu saamine ja API-võtme loomine

API-juurdepääsu hallatakse Kimi Open Platformi konsoolis. Vajate kontot, API-võtit ja konto seadistust, mis lubab API-d kasutada. Platvorm nõuab enne kasutamist konto väikest ettemakset, seega ei ole juurdepääs sama mis piiranguteta tasuta arendajapakett.

Hoidke võtit serveris või saladuste halduris. Ärge paigutage seda brauseri JavaScripti, mobiilirakendusse, lähtekoodihoidlasse ega kliendipoolsesse HTML-i, kust kasutajad võivad selle kätte saada. Allolevates näidetes eeldatakse, et võtit hoitakse keskkonnamuutujas nimega MOONSHOT_API_KEY.

export MOONSHOT_API_KEY="your-api-key"

Iga päring kasutab päises Authorization Beareri tunnust. Kui päring ebaõnnestub, kontrollige esmalt, kas võti on olemas, valitud mudel on ajakohane, kontol on juurdepääs ja saldo ning päring saadetakse õigesse lõpp-punkti.

API ja mudeli valimine

Vestluste jaoks on kolm peamist liidest:

• Chat Completions: tuttav sõnumipõhine API tavavestluste, voogedastuse, visuaalsisendi, JSON-režiimi ja tööriistakutsete jaoks.
• Responses API: ühtne vastuseliides teksti- või pildisisendi, struktureeritud väljundi, funktsioonitööriistade ja serveripoolse veebiotsingu jaoks.
• Messages API: Anthropicuga ühilduv liides aadressil /anthropic/v1/messages rakendustele, mis kasutavad Anthropicule omaseid päringuvorminguid.

Kasutage Chat Completionsi, kui soovite lihtsaimat OpenAI-ga ühilduvat migratsiooniteed. Kasutage Responsesi, kui teie rakendus saab kasu selle ühtsest vastusevormingust, struktureeritud väljundist, funktsioonitööriistadest või majutatud veebiotsingust. Kasutage Messagesi API-t, kui peamine nõue on ühilduvus Anthropicule suunatud koodibaasiga.

Praeguses mudeliloendis on kimi-k3, kimi-k2.7-code, kimi-k2.7-code-highspeed ja kimi-k2.6. Kimi K3 on uute rakenduste jaoks soovitatav üldotstarbeline lähtekoht ning pakub 1 miljoni märgi suurust kontekstiakent ja natiivset visuaalset mõistmist. Kimi K2.7 Code on suunatud tarkvaraarendusele ja selle kontekstiaken on 256K; selle suure kiirusega variant on mõeldud latentsustundlike programmeerimistöövoogude jaoks. Kimi K2.6 toetab teksti-, pildi- ja videosisendit ning mõtlemis- ja mittemõtlemisrežiimi.

Enne mudeli identifikaatori kasutuselevõttu kontrollige kehtivat mudelidokumentatsiooni. Esitatud praegustes mudelijuhistes on Moonshot V1, Kimi K2.5, Kimi K2 eelvaatemudelid, kimi-latest ja kimi-thinking-preview märgitud lõpetatuks või uute integratsioonide jaoks sobimatuks.

Esimese päringu tegemine

Järgmine päring kasutab OpenAI-ga ühilduvat Chat Completionsi lõpp-punkti. API versiooni saab valida, muutes baas-URL-i väärtuseks https://api.moonshot.ai/v1.

curl --fail-with-body --silent --show-error https://api.moonshot.ai/v1/chat/completions 
  -H "Authorization: Bearer ${MOONSHOT_API_KEY}" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain what an API is in one sentence."}
    ]
  }'

Edukas Chat Completionsi vastus sisaldab valikute loendit. Genereeritud tekst loetakse tavaliselt väärtusest choices[0].message.content. Vastus sisaldab ka metaandmeid, näiteks mudelit ja kasutusteavet, mille abil saab jälgida märgikulu.

OpenAI-ga ühilduva Pythoni SDK kasutamine

Moonshot AI toetab ametlikku OpenAI Pythoni SDK-d, kui määrate Kimi baas-URL-i. Allolevas näites kasutatakse SDK paketi ja kliendi süntaksis OpenAI praegust 1.x-laadset liidest.

import os
from openai import OpenAI

api_key = os.environ.get("MOONSHOT_API_KEY")
if not api_key:
    raise RuntimeError("Set MOONSHOT_API_KEY before running this example")

client = OpenAI(
    api_key=api_key,
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "What is an API?"},
    ],
)

print(response.choices[0].message.content)

Ametlikke OpenAI Node.js-i SDK-sid saab üldjoontes seadistada samal viisil, määrates Kimi baas-URL-i. Ametlikke Anthropic SDK-sid toetatakse Anthropicuga ühilduva Messagesi lõpp-punkti kaudu. Toores HTTP-päring on saadaval ka mis tahes programmeerimiskeeles, sealhulgas PHP-s.

Kuidas Kimi API hinnastamine toimib

Kimi API kasutab järelduste tegemisel tavapärase kuutellimuse asemel kasutuspõhist arveldamist. Mudeli kasutust arveldatakse sisend- ja väljundmärkide tarbimise järgi. Sisendmärgid tähistavad mudelile saadetud sisu, väljundmärgid aga genereeritud sisu. Seetõttu võivad pikad viibad, vestlusajalugu, hangitud dokumendid ja ekstraheeritud failid suurendada sisendkasutust.

K3 mudelid toetavad vahemäluteadlikku hinnastamist, mille puhul vahemällu kirjutamise ja vahemällu salvestatud sisendi käitumine on seotud vahemälu säilitusaja seadistustega. Pakktöötlusel on eraldi hinnastamine ning see on mõeldud asünkroonseks hulgatöötluseks tavapäraste päringutega võrreldes väiksema kuluga. Esitatud dokumentatsiooni kohaselt on failide üleslaadimise ja ekstraheerimise API-d ajutiselt tasuta, kuid failidest ekstraheeritud ja mudelile edastatud teksti arveldatakse sisendina.

Täpsed märgihinnad sõltuvad mudelist ja võivad muutuda, seega tutvuge praeguse hinnastamise dokumentatsiooniga, selle asemel et kodeerida hind rakenduse loogikasse või tugineda vanale näitele. Ka veebiotsingu päringutel on eraldi hinnastamis- ja kvooditingimused.

Arendajatele kättesaadavad põhivõimalused

Voogedastatavad vastused

Voogedastus saadab genereeritud sisu järk-järgult serveri saadetud sündmustena, selle asemel et oodata täieliku vastuse valmimist. See on vestlusliideste puhul kasulik, sest rakendus saab vastuse algust kuvada samal ajal, kui mudel jätkab genereerimist.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Explain event-driven architecture."},
    ],
    stream=True,
)

for chunk in stream:
    if chunk.choices:
        text = chunk.choices[0].delta.content
        if text:
            print(text, end="", flush=True)
print()

Struktureeritud JSON-väljund

JSON-režiim palub mudelil tagastada tavapärase proosa asemel JSON-objekti. Chat Completionsi puhul määrake response_format väärtuseks {"type": "json_object"} ning valideerige ja parsige tulemus siiski rakenduse koodis. JSON-režiim ei kaota vajadust veakäsitluse järele: rakendus peab toime tulema vigase väljundi, puuduvate väljade, ootamatute väärtuste ja teenusevigadega.

import json

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "Return only valid JSON."},
        {"role": "user", "content": "Return name and category for Moonshot AI."},
    ],
    response_format={"type": "json_object"},
)

result = json.loads(response.choices[0].message.content)
print(result)

Responsesi API dokumentatsioon kirjeldab struktureeritud väljundit ka selle response-format-liidese kaudu. Kasutage valitud lõpp-punkti ja mudeli toetatud liidest ning valideerige dekodeeritud objekt oma rakenduse skeemi alusel.

Funktsioonide ja tööriistade kutsumine

Funktsioonikutsed võimaldavad mudelil paluda toimingut, mille teie rakendus täidab. Näiteks võib mudel paluda ilmaandmete päringut, andmebaasipäringut või ettevõtte sisetoimingut. Rakendus vastutab endiselt funktsiooni käivitamise, õiguste kontrollimise, argumentide valideerimise ja tulemuse tagastamise eest. Mudel ei saa teie süsteemidele automaatselt juurdepääsu lihtsalt seetõttu, et funktsioon on deklareeritud.

weather_tool = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
            "additionalProperties": False,
        },
    },
}

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "What is the weather in Beijing?"},
    ],
    tools=[weather_tool],
    tool_choice="auto",
)

message = response.choices[0].message
if message.tool_calls:
    for tool_call in message.tool_calls:
        if tool_call.function.name == "get_weather":
            arguments = json.loads(tool_call.function.arguments)
            print("Requested city:", arguments["city"])
else:
    print(message.content)

Tootmiskeskkonnas saadetakse tööriista tulemus tavaliselt järelpäringuga tagasi, et mudel saaks koostada lõpliku vastuse. Säilitage tööriistakutse identifikaatorid, valideerige JSON-argumendid, piirake lubatud toiminguid ja ärge lubage mudeli genereeritud argumentidel autoriseerimisest mööda minna.

Pildid, video ja failid

Toetatud Kimi mudelid aktsepteerivad multimodaalset sisendit. Pildiandmeid saab edastada URL-i või base64-andme-URL-ina. Praegune dokumentatsioon kirjeldab toetatud mudelite puhul ka videosisendit. Platvorm pakub dokumentide, piltide ja video üleslaadimise ning ekstraheerimise töövooge. Ekstraheeritud dokumenditekst lisatakse mudelipäringusse ja selle eest arveldatakse sisendmärkidena isegi siis, kui üleslaadimise ja ekstraheerimise toiming ise on ajutiselt tasuta.

Failitöötlus on kasulik dokumentide kohta küsimustele vastamisel, uurimistöös, arvutustabeli- ja aruandetöövoogudes ning visuaalanalüüsis. Rakendused peaksid siiski kontrollima faili suurust, failitüüpi, tundlikku teavet, säilitamise ootusi ja igas päringus sisalduva ekstraheeritud sisu mahtu.

Veebiotsing ja URL-ide sisu hankimine

Platvorm pakub spetsiaalseid veebiotsingu ja URL-ide sisu hankimise lõpp-punkte ning toetatud mudelitöövoogude jaoks ametlikke veebiotsingu tööriistu. Need funktsioonid võivad toetada uurimis- ja ajakohase teabe rakendusi, kuid otsingupäringutel on eraldi hinnastamis- ja päringulimiitidega seotud tingimused. Käsitlege hangitud lehti ebausaldusväärse välise sisuna ning rakendage sama valideerimist ja viipemanipulatsiooni vastaseid kaitsemeetmeid nagu teiste veebiga ühendatud süsteemide puhul.

Playground ja arendajatööriistad

Veebipõhine Kimi Playground võimaldab arendajatel testida viipasid, võrrelda praeguseid mudeleid, häälestada parameetreid, proovida tööriistu, uurida märgikasutust ja genereerida päringukoodi. See on kasulik viiba või API-funktsiooni katsetamiseks enne täieliku rakenduse kirjutamist.

Ametlik dokumentatsioon sisaldab kiirjuhendeid, API viiteid, mudelite teavet, hinnastamisjuhiseid, migratsiooniteateid, failinäiteid, tööriistakutsete juhiseid, veateateid ja tõrkeotsingu materjale. Playgroundi katsetest tootmiskeskkonda liikudes kasutage praegust mudeliloendit ja dokumentatsiooni, sest vanemates näidetes võivad olla viited lõpetatud mudeliperekondadele.

Limiidid ja tootmiskeskkonna kaalutlused

Päringulimiidid sõltuvad konto ettemaksest ja konto tasemest. Need võivad hõlmata samaaegsust, päringuid minutis, märke minutis ja märke päevas. Veebiotsingu lõpp-punktid kasutavad eraldi päringute arvuga sekundis mõõdetavat kvooti. Täpsed kvoodid võivad kontoti erineda ja muutuda mahu või riskikontrolli sündmuste ajal.

Kvoodi ületamisel võib API tagastada HTTP 429 koos päringulimiitide päistega. Tootmiskliendid peaksid neid päiseid uurima, kordama päringut ainult sobivatel juhtudel ning kasutama eksponentsiaalset tagasipöördumist koos juhusliku hajutusega. Määrake ka päringute ajalõpud, logige päringu identifikaatoreid ja kasutusteavet turvaliselt ning jälgige latentsust, märgikulu, vahemälu käitumist, mudelivigu ja ebaõnnestunud tööriistakutseid.

Platvormi põhiline vestlus-API on olekuta. Kui rakendus vajab vestlusajalugu, kasutajaeelistusi, õigusi või püsivat agendi olekut, peab rakendus seda teavet ise salvestama ja haldama. Agentide loomise juhised ei nõua eraldi püsivat Assistantsi-objekti; arendajad rakendavad üldjuhul ise püsivuse, tööriistade käivitamise, autoriseerimise ja korduskatsete loogika.

Privaatsustingimused vajavad erilist tähelepanu. Avalikus Kimi OpenPlatformi privaatsuspoliitikas öeldakse, et Moonshot AI võib kasutada viipasid, faile, genereeritud sisu, kontoteavet ja kasutusandmeid oma teenuste pakkumiseks, täiustamiseks ja arendamiseks, sealhulgas aluseks oleva tehnoloogia treenimiseks ja täpsustamiseks. Esitatud dokumentatsioonist ei leidnud kinnitust tavapärase API-liikluse üldisele treenimisest loobumise garantiile. Zero Data Retention on loetletud ettevõtetele mõeldud andmekaitse režiimina, kuid sobivus, lepingutingimused, säilitamise kontrollid ja piirkondlikud töötlemiskorraldused tuleks enne tundliku teabe saatmist Moonshot AI-ga otse üle kontrollida.

Millal on Kimi API hea või halb valik?

Kimi API on tugev kandidaat, kui teie meeskond soovib OpenAI-ga ühilduvat migratsiooniteed, väga pikka konteksti dokumentide või koodi jaoks, multimodaalset sisendit, majutatud veebiotsingu võimalusi, tööriistakutseid, JSON-vastuseid, failitöövooge või juurdepääsu nii tavapärastele kui ka programmeerimisele keskendunud Kimi mudelitele. Ühilduvus OpenAI ja Anthropic SDK mustritega võib vähendada vajaliku integratsioonikoodi hulka.

See võib olla halb valik, kui teie rakendus vajab kindlaid ja kõigile alati kättesaadavaid kvoote, selgelt kontrollitud treenimisest loobumise poliitikat tavapärase API-liikluse jaoks, garanteeritud piirkondlikku töötlemist väljaspool dokumenteeritud korraldusi või täielikult hallatud püsivat agendi olekut. Rangete vastavusnõuetega meeskonnad peaksid enne tootmiskasutust privaatsuspoliitika ja ettevõtetele mõeldud tingimused üle vaatama. Ettearvatava suure koormusega töövoogude puhul tuleks võrrelda ka praeguseid mudeli-, pakktöötluse-, otsingu- ja vahemäluhindu ning kinnitada kontotaseme limiidid.

Esimese projekti jaoks looge kaitstud API-võti, alustage mudeliga kimi-k3, tehke lihtne Chat Completionsi päring, uurige vastuse- ja kasutusvälju ning lisage seejärel ükshaaval voogedastus, struktureeritud väljund, tööriistad, failid või veebiotsing. Enne kasutuselevõttu kontrollige uuesti ametlikku mudeliloendit ja migratsiooniteateid.