BytePlus ModelArk

Mis on ByteDance Seed API ja millal seda kasutada

ByteDance’i Seed-mudelite praegune arendaja-API on saadaval BytePlus ModelArki kaudu. ModelArk on hallatav mudelite teenindamise platvorm, mis pakub konsooli, mudelite aktiveerimist, API-võtmeid, lõpp-punkte, arveldust, mänguvälja, dokumentatsiooni ja halduskontrolle, mida on vaja Seed-mudelite rakendusest kutsumiseks.

ModelArk toetab OpenAI-ga ühilduvaid integratsioonimustreid, sealhulgas Chat Completionsi ja Responses API-sid. See teeb sellest praktilise valiku arendajatele, kes tunnevad juba standardseid vestlussõnumitel põhinevaid päringuid või soovivad ühendada olemasoleva OpenAI-ga ühilduva kliendi BytePlusi taristuga.

Kasuta ModelArki siis, kui vajad versioonitud Seed-mudeleid teksti genereerimiseks, arutlemiseks, programmeerimiseks, multimodaalseks mõistmiseks, tööriistade kasutamiseks, failipõhisteks töövoogudeks, agentideks või peenhäälestuseks. See sobib vähem juhul, kui vajad üht ülemaailmselt ühtset tarbijatoodet, kõigi mudelite puhul identset käitumist või kogu ByteDance’i tehisintellekti ökosüsteemi jaoks ühtset hinnastamis- ja kättesaadavuspoliitikat.

Juurdepääsu ja autentimisandmete hankimine

1. Loo BytePlusi konto või kasuta olemasolevat kontot ja ava ModelArki konsool.
2. Aktiveeri oma projekti jaoks vajalik Seed-mudel. Mudeli kättesaadavus võib sõltuda kontost, piirkonnast, projektist ja mudelist.
3. Loo konsoolis pikaajaline ModelArki API-võti.
4. Salvesta võti keskkonnamuutujasse, näiteks ARK_API_KEY, selle asemel et paigutada see otse lähtekoodi.
5. Kasuta konsooli ja dokumentatsiooni esitatud piirkondlikku baas-URL-i. Üks dokumenteeritud lõpp-punkti näide on https://ark.ap-southeast.bytepluses.com/api/v3.

Päringud autentitakse kandja märgendiga päises Authorization. Suuremate või rangemalt hallatud juurutuste jaoks pakub ModelArk ka järeldamise lõpp-punkte ja täiendavaid juurdepääsukontrolli võimalusi.

API ja mudeli valimine

Tavapärase vestluse või lihtsa teksti genereerimise päringu puhul alusta OpenAI-ga ühilduvast Chat API-st. See kasutab mudeli identifikaatorit ja rollipõhiste sõnumite massiivi. Chat Completions toetab ühilduvate mudelite korral ka voogedastust, tööriistakutseid ja struktureeritud vastusevorminguid.

Responses API on mõeldud uuemate agendipõhiste töövoogude jaoks, sealhulgas püsiva vastusekonteksti, failipõhiste multimodaalsete sisendite ja tööriistakutsete jätkamise jaoks. Vali see siis, kui rakendus vajab enamat kui lihtsat päringu ja vastuse vahetust.

ModelArk kasutab versioonitud mudeliidentifikaatoreid. Praeguse platvormi kohta dokumenteeritud näited on seed-2-0-lite-260428, seed-2-0-mini-260428, seed-2-0-pro-260328 ja seed-1-8-251228. Need identifikaatorid ja nende võimalused võivad muutuda, seega peaksid tootmisrakendused kindla versiooni lukustama ning enne muutmist kontrollima mudelite ajakohast viidet.

Esimese päringu tegemine

Järgmises curl-i näites kasutatakse Chat Completionsiga ühilduvat lõpp-punkti. See saadab süsteemijuhise ja kasutaja sõnumi ning väljastab tagastatud teksti käsuga jq.

curl --fail-with-body -sS https://ark.ap-southeast.bytepluses.com/api/v3/chat/completions 
  -H "Authorization: Bearer ${ARK_API_KEY:?Set ARK_API_KEY}" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "seed-2-0-lite-260428",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain API rate limits in two sentences."}
    ],
    "stream": false
  }' | jq -r '.choices[0].message.content'

Olulised päringu väljad on mudeliidentifikaator, sõnumid ja säte stream. Täpne mudel peab olema valitud konto ja piirkonna jaoks aktiveeritud ning toetatud.

Vastuse mõistmine

Eduka Chat Completionsi vastuse korral paikneb genereeritud assistendi sõnum esimeses valikus, millele pääseb tavaliselt ligi kujul choices[0].message.content. Rakendused peavad siiski arvestama olukordadega, kus vastus sisaldab tööriistakutseid, tühja sisu väärtust või tavalise teksti asemel veateadet.

Tootmiskoodis kontrolli HTTP olekut, säilita kasulikud veadetailid ja ära eelda, et kõik mudelid tagastavad samad valikulised väljad. Vastuseparameetrite ja ühilduvuse puhul tuleb lähtuda konkreetse mudeli dokumentatsioonist.

Kuidas ModelArki hinnastamine toimib

ModelArk kasutab kasutuspõhist ja mitmekesist hinnastamist, mitte üht abonemendihinda kõigi Seed-mudelite jaoks. Keelemudelite eest arveldatakse üldjuhul sisend- ja väljundmärgendite kasutuse põhjal. Vahemällu salvestatud sisendit ja vahemälu salvestamist võidakse käsitleda eraldi ning paketttöötluse korral kehtivad võimaluse korral eraldi soodushinnad märgenditele.

Muud mudelikategooriad kasutavad teistsuguseid ühikuid. Pildigeneratsiooni hind võib olla määratud pildi kohta, video- ja spetsiaalsete mudeliühikute teenused võivad aga kasutada mudelipõhist märgendite, tunni, kuu või muud arvestust.

Avaldatud näidete hulgas on seed-2-0-lite-260428 hinnaga 0,25 USA dollarit miljoni sisendmärgendi kohta ja 2,00 USA dollarit miljoni väljundmärgendi kohta kuni 128K märgendiga viipade puhul. Sama avaldatud hinnatase loetleb seed-2-0-mini-260428 hinnaga 0,10 USA dollarit miljoni sisendmärgendi kohta ja 0,40 USA dollarit miljoni väljundmärgendi kohta. Need on mudeli- ja versioonipõhised näited, mitte universaalne Seedi hind. Kontrolli enne kulude hindamist kehtivat hinnakirja, eriti juhul, kui mängu tulevad viiba pikkus, vahemällu salvestamine, paketttöötlus või mõni muu mudel.

Arendajatele kättesaadavad võimalused

Väljundi voogedastus

Määra stream väärtuseks true, et saada väljundit järk-järgult, mitte oodata täieliku vastuse valmimist. Voogedastus võib parandada pikkade vastuste ja keerukate arutlusülesannete tajutavat reageerimiskiirust, kuid klient peab töötlema osalisi sündmusi ja tulema toime katkenud ühendustega.

Funktsioonide ja tööriistade kutsumine

Ühilduvad mudelid võivad taotleda rakenduse määratud funktsioone, kasutades JSON-skeemiga kirjeldatud tööriistu. Rakendus vastutab endiselt funktsiooni käivitamise, argumentide valideerimise ja tulemuse mudelile tagasi saatmise eest. Tööriistakutsed on kasulikud näiteks teenuse oleku kontrollimiseks, sisemise süsteemi päringute tegemiseks või kontrollitud äritoimingu käivitamiseks.

Struktureeritud väljundid

ModelArki dokumentatsioon kirjeldab struktureeritud väljundite tuge response_format kaudu, sealhulgas JSON-objekti ja JSON Schema režiime. See on kasulik siis, kui rakenduse kood vajab vabas vormis proosa asemel ettearvatavaid välju. Dokumentatsioon määratleb struktureeritud väljundid mõne mudeliversiooni puhul beetafunktsioonina, seega kontrolli enne tootmises sellele tuginemist ühilduvust.

Multimodaalne sisend ja failid

Asjakohased Seed-mudelid võivad toetada piltide, video, heli ja teksti mõistmist. Files API võtab vastu faile ja URL-e hilisemate päringute jaoks, sealhulgas pildi-, video-, dokumendi- ja agendipõhiste töövoogude jaoks, lähtudes mudeli ja failitüübi piirangutest.

Dokumentatsiooni kohaselt säilitatakse üles laaditud videofaile asjakohastes töövoogudes vaikimisi seitse päeva; seadistatav kehtivusaeg võib ulatuda ühest kuni kolmekümne päevani. Toetatud töövoogudes saab kasutada ka BytePlusi TOS-i põhist salvestust, kui vaja on pikemat või kliendi kontrolli all olevat säilitusaega.

Agendid ja peenhäälestus

ModelArk pakub agendi-API-sid seadistatavate tööriistade, oskuste, MCP-serverite, failide, sessioonide ja püsiva agendikonfiguratsiooniga. Samuti pakub see sobivate mudelite ja juurutuskonfiguratsioonide jaoks peenhäälestuse töövooge ning peenhäälestusjärgset järeldamist. Need funktsioonid nõuavad rohkem seadistamist kui lihtne vestluspäring ning neid tuleks hinnata konkreetse mudeli ja konto dokumentatsiooni põhjal.

Pythoni SDK näide struktureeritud väljundiga

OpenAI Pythoni paketi saab seadistada kasutama ModelArki ühilduvat baas-URL-i. Selles näites küsitakse versioonitud Seed-mudelilt JSON Schema vormis vastust.

# Install: pip install --upgrade "openai>=1.0"
import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ARK_API_KEY"],
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3",
    timeout=1800.0,
)

response = client.chat.completions.create(
    model="seed-2-0-lite-260428",
    messages=[
        {"role": "system", "content": "You are a precise technical assistant."},
        {"role": "user", "content": "Give two recommendations for a reliable API client."},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "recommendations",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "recommendations": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["recommendations"],
                "additionalProperties": False
            }
        }
    }
)

content = response.choices[0].message.content
print(json.dumps(json.loads(content), indent=2))

Kuna struktureeritud väljundid sõltuvad mudelist ja võivad olla beetafunktsioon, peaks tootmiskood käsitlema toetamata parameetreid ning valideerima tagastatud JSON-i enne selle kasutamist.

JavaScripti näide tööriista määratlusega

Järgmine näide näitab sama OpenAI-ga ühilduvat kliendistiili koos funktsioonitööriistaga. ModelArk tagastab tööriistakutse, kui mudel otsustab, et rakenduse funktsiooni on vaja; rakendus peab selle käivitama ja tulemuse töötlema.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ARK_API_KEY,
  baseURL: "https://ark.ap-southeast.bytepluses.com/api/v3",
  timeout: 1800000
});

const completion = await client.chat.completions.create({
  model: "seed-2-0-lite-260428",
  messages: [
    { role: "user", content: "Check the status of the payments service." }
  ],
  tools: [
    {
      type: "function",
      function: {
        name: "lookup_service_status",
        description: "Return the service status for a named service.",
        parameters: {
          type: "object",
          properties: { service: { type: "string" } },
          required: ["service"],
          additionalProperties: false
        },
        strict: true
      }
    }
  ],
  tool_choice: "auto"
});

const message = completion.choices?.[0]?.message;
if (!message) throw new Error("No assistant message returned");

console.log(message.content ?? "");
for (const call of message.tool_calls ?? []) {
  console.log(call.function.name, JSON.parse(call.function.arguments));
}

SDK-d, mänguväljak ja arendajatööriistad

ModelArk dokumenteerib OpenAI-ga ühilduvaid Pythoni ja JavaScripti integratsioone. BytePlusi või ModelArki SDK näited on saadaval ka Pythoni, Go, Java ja muude toetatud keskkondade jaoks. Kasuta üht järjepidevat SDK põlvkonda ja kontrolli enne näite projekti kopeerimist kehtivat paketidokumentatsiooni.

ModelArki konsool ja mänguväljak võimaldavad arendajatel mudeleid enne rakendusse integreerimist katsetada. Dokumentatsioon sisaldab API viiteid, teavet mudelite võimaluste kohta, autentimisjuhiseid, hinnastamist, voogedastust, faile, agente, multimodaalseid töövooge ja arutlemisega seotud juhiseid.

Piirangud ja tootmisega seotud kaalutlused

Keelemudelite piiranguid väljendatakse peamiselt päringute arvuna minutis ja märgendite arvuna minutis. Kvoodid sõltuvad kontost, projektist, mudelist ja lõpp-punktist ning neid saab vaadata ModelArki konsoolis. Platvormi kaudu saab taotleda piirangute suurendamist. Pildi- ja videomudelid võivad kasutada selle asemel piltide arvul minutis põhinevaid või mudelipõhiseid kvoote.

Kogu ModelArki kataloogi jaoks ei ole ühtset avalikku latentsusaja garantiid. Voogedastus võib vähendada tajutavat ooteaega, samal ajal kui paindlikud teenusetasemed, ette nähtud lõpp-punktid või mudeliühikud võivad toetada töökoormusi, mille puhul on vaja paremini kontrollitud läbilaskevõimet või latentsusaega.

Tootmisrakendused peaksid ajutiste rikete korral kasutama piiratud eksponentsiaalset korduskatset, järgima RPM- ja TPM-piiranguid, hoidma API-võtmed kliendipoolsest koodist eemal, logima päringu identifikaatoreid ja vigu turvaliselt ning mitte eeldama, et ühe mudeli parameetrid toimivad kõigi teiste Seed-mudelite puhul. Lukusta mudeliversioonid, jälgi aegumisteateid ja testi muudatusi tüüpiliste viipadega.

BytePlusi sõnul ei kasutata ModelArki kliendiandmeid mudelite treenimiseks ega optimeerimiseks, välja arvatud juhul, kui klient annab selleks eraldi nõusoleku. Andmeid võidakse siiski töödelda teenuse osutamiseks, ohutuse ja kuritarvituste tuvastamiseks, tõrkeotsinguks, turvauurimisteks ning koondatud teenusestatistika koostamiseks. Enne konfidentsiaalse või reguleeritud teabe saatmist vaata üle kohaldatavad teenusetingimused.

Millal on ModelArk hea või halb valik

See on hea valik, kui:

• Soovid arendajana kasutada ByteDance’i Seed-mudeleid hallatavate API-de kaudu.
• Su meeskond kasutab juba OpenAI-ga ühilduvaid Chati või Responses API töövooge.
• Vajad teksti, programmeerimise, multimodaalse, tööriista-, faili-, agendi- või peenhäälestuse töövoogude kombinatsiooni.
• Suudad hallata mudelite aktiveerimist, piirkondlikke lõpp-punkte, versioonitud identifikaatoreid ja kasutuspõhist arveldust.
• Soovid enne tootmisintegratsiooni loomist kasutada mänguväljakut ja dokumenteeritud platvormifunktsioone.

See võib olla halb valik, kui:

• Vajad üht järjepidevat ülemaailmset lõpp-punkti ja kõigi mudelite puhul identseid võimalusi.
• Vajad läbipaistvat fikseeritud hinda, mis ei sõltu mudeliversioonist, viiba pikkusest, vahemällu salvestamisest ega meediatüübist.
• Sinu kasutajad vajavad eraldiseisvat tarbijaassistenti, mitte rakenduste arendusplatvormi.
• Sinu juurutus ei saa arvestada piirkondliku kättesaadavuse, konto aktiveerimise või muutuvate mudeliversioonidega.
• Vajad universaalset veebist otsimise funktsiooni; dokumenteeritud veebiotsing on saadaval Info Quest MCP integratsiooni kaudu, mitte kõigi Seed-mudelite puhul garanteeritult.

Praktilises mõttes tasub BytePlus ModelArki hinnata kui hallatavate mudeliteenuste perekonda. API ülesehitus on tuttav, kuid tootmises olulised üksikasjad – mudeli tugi, hinnastamine, kvoodid, säilitamine ja funktsioonide ühilduvus – tuleb üle kontrollida täpselt selle mudeli, piirkonna ja konto konfiguratsiooni puhul, mida kavatsed kasutada.