Siirry sisältöön
Toiminto kutsu

Toiminto kutsu

Kuvaa funktiosi pyynnössä, niin malli vastaa kutsuilla, jotka se haluaa suoritettaviksi. Koodisi suorittaa ne ja lähettää tulokset takaisin: API palauttaa työkalukutsut mutta ei suorita työkalua itse.

POST https://api.shannon-ai.com/v1/chat/completions

Tämän sivun esimerkit käyttävät päätepistettä /v1/chat/completions. Sama silmukka toimii päätepisteissä /v1/responses ja /v1/messages; kun jokin muoto kirjoittaa asian eri tavalla, alla olevissa osioissa näkyvät kaikki kolme.

import json
from openai import OpenAI

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

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, for example Paris"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["city"],
        },
    },
}]

def get_weather(city, unit="celsius"):
    # Your code: ask a weather service here.
    return {"city": city, "temperature": 18, "unit": unit, "conditions": "cloudy"}

messages = [{"role": "user", "content": "What is the weather in Paris right now?"}]
answer = None

for _ in range(5):  # the API sets no limit on rounds: set your own
    response = client.chat.completions.create(
        model="Kimi-K3-3BIT-REAP",
        messages=messages,
        tools=tools,
    )
    choice = response.choices[0]
    if choice.finish_reason != "tool_calls":
        answer = choice.message.content
        break

    messages.append(choice.message)  # the assistant turn with its tool_calls
    for call in choice.message.tool_calls:
        args = json.loads(call.function.arguments)  # arguments is a JSON string
        result = get_weather(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

print(answer)

Ensimmäinen vastaus ei vastaa kysymykseen. Se pyytää kutsua:

200 JSON
{
  "id": "chatcmpl-5b0c1d8e7f6a4b3c9d2e1f0a8b7c6d5e",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "reasoning_content": "The user asks for the current weather in Paris. I should call get_weather.",
        "tool_calls": [
          {
            "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Paris\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 312,
    "completion_tokens": 58,
    "total_tokens": 370,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 31}
  }
}

Kun olet lähettänyt tuloksen, seuraava vastaus on tavallinen vastaus: message.content sisältää tekstin ja finish_reason on stop.

Silmukka vaihe vaiheelta

Vaihe Kuka Mitä tapahtuu
1 Sinä Lähetä messages yhdessä tools-kentän kanssa. Se on lista funktioista, joita malli voi pyytää.
2 Malli Vastauksessa on tool_calls ja finish_reason: "tool_calls". Jokainen kutsu nimeää funktion ja antaa sen argumentit.
3 Sinä Jäsennä jokaisen kutsun arguments ja suorita funktiosi.
4 Sinä Lisää avustajan viesti ja yksi tool-viesti kutsua kohti kenttään messages ja lähetä pyyntö uudelleen samoilla tools-arvoilla.
5 Malli Malli vastaa tekstillä ja finish_reason: "stop", tai se pyytää lisää kutsuja. Siinä tapauksessa palaa vaiheeseen 3.

Yksi pyyntö on yksi mallin vuoro. API ei säilytä keskustelua pyyntöjen välillä eikä aseta kierrosten määrää: koodisi pitää messages-listaa ja päättää, milloin lopetetaan.

Työkalujen määrittely

tools on taulukko, jossa on yksi alkio funktiota kohti. Jokainen valikoiman malli hyväksyy sen; GET /v1/models ilmoittaa capabilities.tools: true jokaiselle id:lle.

Kenttä Tyyppi Kuvaus
type string Aina function.
function.name string Nimi, jota malli käyttää pyytäessään tätä funktiota. Pakollinen.
function.description string Mitä funktio tekee, selkeällä kielellä.
function.parameters object Argumentit JSON Schemana, jonka ylimmällä tasolla on type: "object". Katso alla Skeeman avainsanat.

Jokaisella päätepisteellä on oma tapansa kirjoittaa työkalu. Lähetä se, joka kuuluu kutsumaasi päätepisteeseen:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "City name, for example Paris"
        },
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
      },
      "required": ["city"]
    }
  }
}

tool_choice

tool_choice kertoo, saako malli kutsua työkalua tai onko sen pakko. Se luetaan vain yhdessä tools-kentän kanssa.

Arvo Kuvaus Käyttävät mallit
"auto" Malli päättää, vastaako se tekstillä vai kutsuuko se työkalua. Tämä on oletus. Kaikki mallit
"required" Vastaus kutsuu vähintään yhtä työkalua. Hostatut avoimen painon mallit
{"type": "function", "function": {"name": "get_weather"}} Vastaus kutsuu tätä funktiota. Nimen on oltava jokin tools-listan funktioista. Muiden funktioiden kutsut jätetään pois vastauksesta. Hostatut avoimen painon mallit

Shannon-mallit (shannon-*) päättävät jokaisessa pyynnössä itse, kuten arvolla auto.

Kun käytät arvoa required tai nimettyä funktiota, lue finish_reason ennen kuin luet tool_calls. Jos malli ei tuota kutsua, vastaus on tekstivastaus, jossa on finish_reason: "stop".

Merkitys /v1/chat/completions /v1/responses /v1/messages
Malli päättää "auto" "auto" {"type": "auto"}
Kutsu vähintään yhtä työkalua "required" "required" {"type": "any"}
Kutsu yhtä nimettyä funktiota {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Hyväksytään yhteensopivuuden vuoksi: tool_choice: "none" ja parallel_tool_calls. Jos haluat vuoron ilman työkalukutsuja, lähetä pyyntö ilman tools-kenttää.

Työkalukutsut vastauksessa

Kenttä Tyyppi Kuvaus
finish_reason string tool_calls, kun vastaus sisältää vähintään yhden kutsun.
message.tool_calls array Yksi alkio kutsua kohti. Kenttä on mukana vain, kun malli pyysi kutsua.
tool_calls[].id string call_ ja sen perässä 32 heksadesimaalimerkkiä. Lähetä se takaisin tuloksen mukana nimellä tool_call_id.
tool_calls[].type string Aina function.
tool_calls[].function.name string Suoritettava funktio.
tool_calls[].function.arguments string Argumentit JSON-merkkijonona, "{}", kun niitä ei ole. Jäsennä se ennen käyttöä.
message.content string | null null, kun vastaus sisältää vain kutsuja. Hostatut avoimen painon mallit voivat palauttaa tekstiä kutsujen rinnalla; Shannon-mallit palauttavat null.

Sama kutsu kussakin muodossa. Päätepisteessä /v1/responses se on output-listan function_call-alkio, jonka arguments on JSON-merkkijono. Päätepisteessä /v1/messages se on tool_use-sisältölohko, jonka input on JSON-objekti, sen id alkaa merkinnällä toolu_ ja stop_reason on tool_use.

{
  "finish_reason": "tool_calls",
  "message": {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"Paris\"}"
        }
      }
    ]
  }
}

Useita kutsuja yhdellä vuorolla

Vastauksessa voi olla useita kutsuja. Suorita ne kaikki ja lähetä seuraavassa pyynnössä yksi tulos kutsua kohti, kullakin oma tool_call_id.

Hostatut avoimen painon mallit palauttavat jokaisen erilaisen kutsun kerran: kaksi kutsua, joilla on sama nimi ja samat argumentit, saapuvat yhtenä.

Striimatut työkalukutsut

Kun stream: true, kutsu saapuu yhtenä kappaleena: chunk sisältää koko arguments-merkkijonon, joten yhdistettäviä osia ei ole. index laskee vuoron kutsut luvusta 0 alkaen.

data: yksi chunk, muotoiltuna
{
  "id": "chatcmpl-5b0c1d8e7f6a4b3c9d2e1f0a8b7c6d5e",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "Kimi-K3-3BIT-REAP",
  "choices": [
    {
      "index": 0,
      "delta": {
        "tool_calls": [
          {
            "index": 0,
            "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Paris\"}"
            }
          }
        ]
      },
      "finish_reason": null
    }
  ]
}
Päätepiste Mitä saapuu
/v1/chat/completions Yksi chat.completion.chunk kutsua kohti, kutsu kentässä delta.tool_calls[0]. Viimeisessä chunkissa on finish_reason: "tool_calls" ja usage.
/v1/responses Kutsua kohti: response.output_item.added (function_call-alkio, jonka arguments on tyhjä), response.function_call_arguments.delta (koko merkkijono), response.function_call_arguments.done, response.output_item.done.
/v1/messages Kutsua kohti: content_block_start (tool_use-lohko, jonka input on tyhjä), yksi content_block_delta, jonka input_json_delta.partial_json on koko argumenttiteksti, content_block_stop. message_delta sisältää sitten stop_reason: "tool_use".

Malleilla shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ja shannon-coder-1 striimattu pyyntö, jossa on tools, toimittaa vastaustekstin yhtenä content-deltana vuoron lopussa. Suoratoisto

Tulosten lähettäminen takaisin

Toinen pyyntö toistaa keskustelun ja lisää kaksi asiaa: avustajan vuoron, joka pyysi kutsuja, ja yhden tuloksen kutsua kohti.

{
  "messages": [
    {"role": "user", "content": "What is the weather in Paris right now?"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\":\"Paris\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
      "content": "{\"city\":\"Paris\",\"temperature\":18,\"unit\":\"celsius\",\"conditions\":\"cloudy\"}"
    }
  ]
}
  • Lähetä avustajan vuoro takaisin sellaisena kuin sait sen, ennen tuloksia. Jokainen tulos yhdistetään kutsuunsa id:llä: tool_call_id päätepisteessä /v1/chat/completions, call_id päätepisteessä /v1/responses, tool_use_id päätepisteessä /v1/messages.
  • Tulos on tekstiä. Serialisoi objekti JSON-merkkijonoksi kenttään content (output päätepisteessä /v1/responses). Päätepisteessä /v1/messages tool_result-lohkon content on merkkijono tai lista tekstilohkoja.
  • Avustajan vuorolla function.arguments pysyy JSON-merkkijonona täsmälleen sellaisena kuin se saapui.
  • Keskustelu voi päättyä työkalun tulokseen. Uutta käyttäjän viestiä ei tarvita: malli jatkaa tuloksesta.
  • Jos funktiosi epäonnistuu, lähetä epäonnistuminen tuloksen tekstinä. Malli voi silloin kertoa siitä tai pyytää uutta kutsua.

Skeeman avainsanat

parameters (input_schema päätepisteessä /v1/messages) on JSON Schema. Shannon 3 -perhe (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ja hostatut avoimen painon mallit saavat sen sellaisena kuin lähetät sen.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro ja shannon-coder-1 saavat tämän osajoukon kaikissa kolmessa päätepisteessä:

Käsittely Avainsanat
Luetaan sellaisenaan Jokainen avainsana, jota ei ole nimetty alla olevilla riveillä, esimerkiksi type, properties, required, items, enum, description, minimum, maximum, anyOf ja allOf, skeeman jokaisella tasolla.
format Luetaan arvoille int32, int64, float, double, byte, date, date-time ja enum.
oneOf Luetaan kuten anyOf.
Ei kuulu skeemaan, jonka nämä mallit saavat $schema, $id, $ref, $defs, $comment, definitions, additionalProperties, unevaluatedProperties, patternProperties, propertyNames, examples, default, title, const, not, if, then, else, contains, minContains, maxContains, dependentRequired, dependentSchemas, dependencies, readOnly, writeOnly, deprecated, contentEncoding, contentMediaType, contentSchema, multipleOf, uniqueItems; exclusiveMinimum ja exclusiveMaximum, kun ne ovat lukuja; format-kentän muut arvot.

Toiminta ja rajat

  • API ei aseta enimmäismäärää työkaluille eikä kierroksille.
  • Pyynnön runko voi olla enintään 32 MiB, ja keskustelun tuloksineen on mahduttava mallin kontekstikokoon.
  • Kun pyynnössä on tools, mallit shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ja shannon-2-pro käyttävät oletuksena temperature-arvoa 0.2. Aseta toinen arvo lähettämällä temperature.
  • Jokainen kierros on oma pyyntönsä: se kuluttaa saldoasi ja lasketaan tulvasuojaan kuten mikä tahansa muu pyyntö. Rajat ja saldo

Virheet

Työkalukutsu on tavallinen vastaus tilalla 200. Nämä virheet koskevat itse pyyntöä:

Tila Tyyppi Viesti Milloin
400 invalid_request_error unknown model: <id> model ei ole julkaistun listan id.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools ei ole taulukko, tai jonkin muun kentän JSON-tyyppi on väärä.
413 invalid_request_error Failed to buffer the request body: … Pyynnön runko on suurempi kuin 32 MiB. Virheessä on code: "request_too_large".

Malli kirjoittaa argumentit. Tarkista ne skeemaasi vasten ennen funktion suorittamista, kuten tarkistaisit mitä tahansa ulkopuolista syötettä.

Todennus-, saldo- ja palvelinvirheet ovat samat kuin kaikissa pyynnöissä. Virheiden käsittely