Databricks Data and AI Developer Platform

Mis on Databricksi API ja millal seda kasutada

Databricksi API on teenuste kogum, mitte üksainus lõpp-punkt. Üldine REST API haldab platvormi ressursse, nagu tööd, arvutusressursid, Unity Catalog, õigused, failid ja teeninduslõpp-punktid. Model Serving teeb kohandatud mudelid, baasmudelid, välised mudelipakkujad ja agendid kättesaadavaks HTTPS-i lõpp-punktide kaudu. Foundation Model API-d annavad juurdepääsu toetatud majutatud mudelitele, ilma et peaksite haldama nende aluseks olevat juurutust. Unity Gateway mudeliteenused pakuvad toetatud mudelite jaoks kontrollitud liidest.

Generatiivse tehisintellekti rakenduste puhul rõhutab Databricks praegu OpenAI-ga ühilduvaid liideseid. Olenevalt teenusest saate kasutada Chat Completionsi, avatud Responses API-t, Databricksi OpenAI klienti, standardset OpenAI Pythoni või JavaScripti klienti, töötlemata HTTP-päringuid või Databricksi SDK-sid.

Databricks sobib hästi siis, kui rakendus vajab lisaks mudelitele juurdepääsu ettevõtte andmetele, Unity Catalogi haldust, juurutamise juhtimist, seiret, mudelite marsruutimist või pilvepõhist taristut. See sobib halvemini neile, kes soovivad lihtsat tarbijatele mõeldud vestlusrobotit või väikest eraldiseisvat mudeli lõpp-punkti minimaalse haldusvajadusega.

Juurdepääsu ja autentimisandmete hankimine

Teil on vaja Databricksi tööruumi või muud toetatud Databricksi juurutust, õigust kasutada vastavat mudeliteenust või teeninduslõpp-punkti ning selle tööruumi aktsepteeritud autentimisandmeid. Juurdepääs võib erineda olenevalt pilvest, piirkonnast, tööruumi tasemest, mudelist, lõpp-punkti konfiguratsioonist ja kontoõigustest.

Databricks soovitab kasutajate ja teenuseidentiteetide puhul OAuthi, eriti automatiseeritud tootmiskoormuste korral. OAuthi loa föderatsioon võib vahetada identiteedipakkuja JWT Databricksi OAuthi loa vastu ja vähendab vajadust hallata pikaajalisi saladusi. Isiklikud juurdepääsuloamärgid on asjakohastes keskkondades endiselt toetatud, kuid paljudes tootmisstsenaariumides eelistatakse neist vähem või käsitletakse neid pärandlahendusena.

Hoidke autentimisandmed lähtekoodist väljaspool. Kasutage keskkonnamuutujaid, saladuste haldurit, töökoormuse identiteeti või OAuthi loa föderatsiooni. Allolevates näidetes kasutatakse päringu arusaadavuse huvides loa keskkonnamuutujat; tootmissüsteemid peaksid kasutama oma juurutusele sobivat autentimisviisi.

Sobiva API ja mudeli valimine

Valige API selle põhjal, mida te juurutate:

Mudelite nimed, toetatud funktsioonid, piirkonnad ja elutsükli olek on mudelipõhised. Databricks võib mudeleid kasutusest kõrvaldada või eemaldada, seega kontrollige enne uude rakendusse mudeli püsikodeerimist selle praegust saadavust. Uue mudeliteenuse integratsiooni korral näeb tööruumipõhine baas-URL tavaliselt välja nii: https://<workspace-url>/ai-gateway/mlflow/v1. Otse juurutatud teeninduslõpp-punkt kasutab üldjuhul väärtust https://<workspace-url>/serving-endpoints.

Esimese päringu tegemine

Järgmises näites kasutatakse praegust OpenAI-ga ühilduvat Chat Completionsi mustrit. Asendage tööruumi URL, luba ja mudeliteenus oma Databricksi keskkonnas saadaolevate väärtustega. Näidatud mudelitunnus pärineb dokumenteeritud mustrist; mudeli saadavus võib erineda.

curl -sS -X POST "https://${DATABRICKS_WORKSPACE_URL}/ai-gateway/mlflow/v1/chat/completions" 
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "system.ai.claude-sonnet-4-5",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain Databricks Model Serving in one paragraph."}
    ],
    "max_tokens": 256,
    "temperature": 0.2
  }'

Otse juurutatud Model Servingu lõpp-punkt kasutab mudeli väärtusena teeninduslõpp-punkti nime ja tavaliselt teeninduslõpp-punktide baas-URL-i. Traditsiooniline kutsumisteekond on endiselt saadaval aadressil /serving-endpoints/{name}/invocations. Responses-tüüpi päringute puhul dokumenteerib Databricks tee /serving-endpoints/open-responses ning kasutab välja input Chat Completionsi välja messages asemel.

Vastuse mõistmine

Chat Completionsi vastused järgivad tuttavat OpenAI-ga ühilduvat struktuuri. Genereeritud tekst on tavaliselt saadaval aadressil choices[0].message.content. Vastus võib lõpliku vastuse asemel sisaldada ka tööriistakutse teavet, kui mudel otsustab, et käivitada tuleb rakenduse funktsioon.

Responses-tüüpi päringud kasutavad väljundmassiivi ja võivad toetada pakkujast sõltumatuid funktsioone, nagu arutluskäik, tööriistakutsed, struktureeritud väljund ja pildisisend, kui valitud mudel neid toetab. Ärge eeldage, et kõik mudelid või lõpp-punktid pakuvad samu välju. Saadaolevad funktsioonid sõltuvad teenindusrežiimist ja valitud pakkujast.

Kuidas Databricksi hinnastamine üldjoontes toimib

Databricksi hinnastamine põhineb kasutusel, mitte ühel universaalsel API tellimishinnal. Kogukulu sõltub pilvest, piirkonnast, tööruumi tasemest, tootest, mudelist, juurutusrežiimist ja töökoormusest.

• Foundation Model API-de tasu võib põhineda sisend- ja väljundtokenitel ning päringupõhistel kvootidel.
• Model Serving võib kasutada tokenipõhist, prioriteetset tokenipõhist või ette broneeritud läbilaskevõimega teenindust või arvutuspõhist teenindust.
• Üldise platvormi funktsioonide eest tasutakse Databricksi ühikute ja nendega seotud pilvetaristu tasude kaudu.
• Kohandatud mudelitel, agentidel, välistel mudelilõpp-punktidel ja toetavatel andmeteenustel võib olla teistsugune kulumuster.

Hinnangute tegemiseks kasutage praegust pilvepõhist Databricksi hinnakirja. Ärge käsitlege ühe mudeli, pilve või teenindusrežiimi hinda universaalse API hinnana. Tootmises jälgige tokenikasutust, lõpp-punkti kasutust, taristutasusid ning lubatud järeldus- või kasutustabeleid eraldi.

Olulised võimalused

Vastuste voogedastus

Ühilduvad vestluse, lõpetamise, agendi ja Responses-tüüpi töökoormused võivad toetada voogedastust. Selle asemel et oodata kogu vastuse valmimist, saab klient järk-järgult sündmusi või osi ning võib teksti kuvada selle saabumise ajal. Täpne sündmuste struktuur sõltub kasutatavast API-st.

curl -N -sS -X POST "https://${DATABRICKS_WORKSPACE_URL}/ai-gateway/mlflow/v1/chat/completions" 
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "system.ai.claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Give three practical Databricks API use cases."}],
    "stream": true,
    "max_tokens": 256
  }'

Funktsioonikutsed ja tööriistad

Funktsioonikutsed võimaldavad mudelil tagastada struktureeritud päringu rakenduse määratud funktsiooni kutsumiseks. Funktsiooni käivitab rakendus, mitte mudel; rakendus kontrollib ka argumente ja saadab tulemuse järgmise mudelipäringu kaudu tagasi. See on kasulik mudeli ühendamiseks ettevõttesisese otsingu, piletisüsteemide, andmebaaside või äritoimingutega.

Foundation Model API-de ja väliseid mudeleid toetavate teeninduslõpp-punktide funktsioonikutsed on OpenAI-ga ühilduvad. Saadavus ja tööriistade käitumine on endiselt mudelipõhised. Käsitlege tööriistaargumente ebausaldusväärse sisendina: enne millegi käivitamist kontrollige tüüpe, õigusi, lubatud toiminguid ja autoriseerimist.

Struktureeritud väljundid

Toetatud vestlusmudelid võivad tagastada JSON-objekte või JSON Schema põhiseid vastuseid. Struktureeritud väljund on kasulik siis, kui rakenduse kood vajab vabavormilise teksti asemel prognoositavaid välju. Kehtivad mudelipõhised piirangud ning dokumenteeritud konfiguratsioonid ei saa üldjuhul struktureeritud väljundit voogedastusega ühendada. Claude'i struktureeritud väljundile kehtivad ka täiendavad tööriistu või tööriista valikut puudutavad piirangud.

const structured = await client.chat.completions.create({
  model: "system.ai.claude-sonnet-4-5",
  messages: [{
    role: "user",
    content: "Return a short summary of Databricks Model Serving and two benefits."
  }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "serving_summary",
      strict: true,
      schema: {
        type: "object",
        properties: {
          summary: { type: "string" },
          benefits: { type: "array", items: { type: "string" } }
        },
        required: ["summary", "benefits"],
        additionalProperties: false
      }
    }
  },
  max_tokens: 256
});

Failid ja dokumendid

Databricksi Files API toetab failide üleslaadimist, allalaadimist, loetlemist ja kustutamist Unity Catalogi köidetes ning muudes toetatud asukohtades. See on kontrollitud failihalduse API, mitte universaalne mudelifailide üleslaadimise lõpp-punkt.

Tüüpilise dokumenditöövoo puhul salvestatakse failid kontrollitud köidetesse ning rakendatakse seejärel vajalik sõelumine, tükeldamine, indekseerimine, otsing või agendiga integreerimine. Mõnel spetsiaalsel tootefunktsioonil on eraldi üleslaadimiskäitumine. Näiteks teatud Genie Agenti failide üleslaadimine toimub ainult kasutajaliidese kaudu ja üldise Files API kaudu ei toetata API-põhist üleslaadimist.

Agendid ja mudelite juurutamine

Databricks toetab juurutatud agente Databricks Appsi ja Model Servingu kaudu. Databricks soovitab juurutatud agentidele päringute tegemiseks oma Databricks OpenAI klienti, sest see toetab agentide algupäraseid funktsioone ja voogedastust. Kohandatud mudelid, majutatud mudelid, välised mudelipakkujad ja agendid saab teeninduslõpp-punktide kaudu kättesaadavaks teha, kui toetatud juurutusrežiimid ja õigused seda võimaldavad.

SDK kasutamine

Kuna mudeliteenuse liides ühildub OpenAI-ga, saab standardse OpenAI Pythoni kliendi konfigureerida Databricksi baas-URL-i kasutama. Selles näites kasutatakse järjepidevalt üht praegust SDK põlvkonda.

# Install: pip install -U openai
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DATABRICKS_TOKEN"],
    base_url=f"https://{os.environ['DATABRICKS_WORKSPACE_URL']}/ai-gateway/mlflow/v1",
)

response = client.chat.completions.create(
    model="system.ai.claude-sonnet-4-5",
    messages=[
        {"role": "system", "content": "You are a helpful technical assistant."},
        {"role": "user", "content": "What is Databricks Model Serving?"},
    ],
    max_tokens=256,
)
print(response.choices[0].message.content)

stream = client.chat.completions.create(
    model="system.ai.claude-sonnet-4-5",
    messages=[{"role": "user", "content": "List three API integration tips."}],
    stream=True,
    max_tokens=256,
)
for chunk in stream:
    text = chunk.choices[0].delta.content
    if text:
        print(text, end="", flush=True)
print()

Databricks pakub ka ametlikke SDK-sid ja tööriistu platvormitoiminguteks, MLflow Deployments API-sid, Databricksi CLI-d, toetatud toimingute jaoks mõeldud keelespetsiifilisi tööriistu ning töötlemata REST-juurdepääsu mis tahes keele jaoks. Kasutage tööruumide, tööde, kataloogide, õiguste ja muude platvormiressursside haldamiseks Databricksi-spetsiifilisi SDK-sid, mitte ärge püüdke neid ülesandeid mudelikliendi kaudu täita.

Mänguväljak ja arendajatööriistad

AI Playground pakub interaktiivset võimalust toetatud mudelite testimiseks, vastuste võrdlemiseks ja tööriistakutseid kasutavate agentide prototüüpimiseks. See on saadaval ainult toetatud tööruumides ja piirkondades. REST API viited, mudelite saadavuse dokumentatsioon, SDK-d, CLI ja MLflow juurutustööriistad on kasulikud eksperimendist kontrollitud juurutuseni jõudmisel.

Databricksi arendus nõuab tavaliselt rohkem seadistamist kui eraldiseisev mudeli API. Teil võib olla vaja mõista tööruumide URL-e, Unity Catalogi nimesid, lõpp-punktide õigusi, pilvepiirkondi, teenindusrežiime, mudeli elutsükli olekut, autentimist ja kasutuspõhist arveldamist.

Piirangud ja tootmiskeskkonna kaalutlused

Databricks rakendab lõpp-punkti-, tööruumi-, päringu-, sisendtokeni- ja väljundtokenipiiranguid. Foundation Model API-de piirangud varieeruvad tööruumi taseme, mudeli, juurutusrežiimi ja piirkonna järgi. Ka Model Serving ja REST API-d rakendavad lõpp-punkti- ja tööruumipiiranguid. Kohaldatavaid piire ületavad päringud võivad saada HTTP 429 vastuse.

• Korduskatsete jaoks kasutage piiratud eksponentsiaalset tagasiviivitust.
• Määrake ühenduse ja päringu ajalõpud, selle asemel et lasta päringutel määramata ajaks oodata.
• Jälgige võimaluse korral päringu ID-sid, latentsust, tokenikasutust, vigu ja lõpp-punkti olekut.
• Piirake samaaegsust valitud lõpp-punkti ja tööruumi võimekusele vastavale tasemele.
• Enne juurutamist kontrollige mudeli elutsükli eeskirju ja kavandage mudeli asendamine.
• Enne reguleeritud andmete saatmist vaadake üle andmete asukoha, säilitamise, logimise, järeldustabelite, välise pakkuja ja lepinguga seotud seaded.
• Kasutage tootmisjuurdepääsuks OAuthi, vähimate õiguste põhimõtet, lõpp-punktide ACL-e, võrgukontrolle ja saladuste haldust.

Databricksi sõnul kaitsevad määratud AI-teenused kliendisisu platvormi- ja lepinguliste kontrollimehhanismide abil ega kasuta seda kolmandatele osapooltele kättesaadavaks tehtavate generatiivsete baasmudelite treenimiseks. Säilitamine ja käsitlemine sõltuvad siiski teenusest, pilvest, tööruumi konfiguratsioonist, välisest mudelipakkujast, lepingust ja lubatud logimisest. Ärge üldistage ühe teenuse säilitamiskäitumist kõigile lõpp-punktidele.

Endine Foundation Model Fine-tuning funktsioon ja pärandpakett databricks_genai on kasutusest kõrvaldatud. Praeguse treenimise ja peenhäälestuse puhul tuleks kasutada toetatud AI Runtime'i ja Model Trainingu võimalusi. Treenitud või kohandatud mudeli saab seejärel Unity Catalogis registreerida ja Model Servingu abil juurutada, kui selle arhitektuur, piirkond, kvoodid ja toote saadavus seda toetavad.

Eelised ja piirangud

Miks kasutada Databricksi API-t

• Juurdepääsu mudelitele saab ühendada ettevõtte andmete, Unity Catalogi halduse, õiguste ja auditeerimiskontrollidega.
• OpenAI-ga ühilduvad liidesed vähendavad levinud mudelikutsete jaoks vajaliku rakendusekoodi hulka.
• Model Serving toetab majutatud mudeleid, kohandatud mudeleid, väliseid pakkujaid ja agente.
• Arendajad saavad võimaluse korral valida tokenipõhise, ette broneeritud läbilaskevõimega, prioriteetse või arvutuspõhise teeninduse vahel.
• REST API-sid, SDK-sid, faile, töid, andmeteenuseid ja mudelilõpp-punkte saab hallata ühe laiema platvormi piires.

Millal Databricks võib halvasti sobida

• Lihtsat vestlusrobotit otsiv tavakasutaja võib pidada tööruumi ja pilve seadistamist ebavajalikuks.
• Kulusid võib olla keeruline hinnata, sest need sõltuvad kasutusest, pilvetaristust, mudelist, piirkonnast ja teenindusrežiimist.
• Funktsioonide saadavus ei ole eri mudelite ja lõpp-punktide puhul ühtlane.
• Tasuta või prooviversioonidele mõeldud keskkondadel ja tööruumitasemetel võivad olla olulised kvoodid ja halduspiirangud.
• Arendajad peavad mõistma Databricksi autentimist, õigusi, Unity Catalogi, lõpp-punktide haldust ja mudeli elutsükli muudatusi.

Databricks on kõige tugevam siis, kui rakendus vajab kontrollitud tehisintellekti, mis on integreeritud andmetöötluse, analüütika, masinõppe, juurutamise ja ettevõtte toimingutega. Kui peamine vajadus on eraldiseisev tekstigenereerimise päring minimaalse taristuga, võib lihtsamat eraldiseisvat API-t olla hõlpsam hallata.