Slaan oor na inhoud
Funksie-oproepe

Funksie-oproepe

Beskryf jou funksies in die versoek en die model antwoord met die oproepe wat dit wil hê gemaak moet word. Jou kode voer dit uit en stuur die resultate terug: die API gee gereedskapoproepe terug en voer self nie 'n gereedskap uit nie.

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

Die voorbeelde op hierdie bladsy gebruik /v1/chat/completions. Dieselfde lus werk op /v1/responses en /v1/messages; waar 'n formaat iets anders skryf, wys die afdelings hieronder al drie.

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)

Die eerste antwoord beantwoord nie die vraag nie. Dit vra vir 'n oproep:

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}
  }
}

Nadat jy die resultaat gestuur het, is die volgende antwoord 'n gewone antwoord: message.content hou die teks en finish_reason is stop.

Die lus, stap vir stap

Stap Wie Wat gebeur
1 Jy Stuur messages saam met tools, die lys funksies wat die model mag aanvra.
2 Model Die antwoord dra tool_calls en finish_reason: "tool_calls". Elke oproep noem 'n funksie en gee sy argumente.
3 Jy Parseer die arguments van elke oproep en voer jou funksie uit.
4 Jy Voeg die assistent-boodskap en een tool-boodskap per oproep by messages, en stuur die versoek dan weer met dieselfde tools.
5 Model Die model antwoord in teks met finish_reason: "stop", of vra vir meer oproepe. In daardie geval, gaan terug na stap 3.

Een versoek is een modelbeurt. Die API hou geen gesprek tussen versoeke nie en stel geen getal rondtes nie: jou kode hou messages en besluit wanneer om op te hou.

Gereedskap definieer

tools is 'n skikking met een inskrywing per funksie. Elke model in die katalogus aanvaar dit; GET /v1/models meld capabilities.tools: true vir elke id.

Veld Tipe Beskrywing
type string Altyd function.
function.name string Die naam wat die model gebruik wanneer dit vir hierdie funksie vra. Vereis.
function.description string Wat die funksie doen, in gewone taal.
function.parameters object Die argumente as 'n JSON Schema met type: "object" bo-aan. Sien Skema-sleutelwoorde hieronder.

Elke eindpunt het sy eie skryfwyse vir 'n gereedskap. Stuur die een wat by die eindpunt hoort wat jy oproep:

{
  "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 bepaal of die model 'n gereedskap mag, of moet, oproep. Dit word net saam met tools gelees.

Waarde Beskrywing Toegepas deur
"auto" Die model besluit of dit in teks antwoord of 'n gereedskap oproep. Dit is die verstek. Alle modelle
"required" Die antwoord roep minstens een gereedskap. Gehuisveste oopgewig-modelle
{"type": "function", "function": {"name": "get_weather"}} Die antwoord roep hierdie funksie. Die naam moet een van die funksies in tools wees. Oproepe na ander funksies word uit die antwoord gelaat. Gehuisveste oopgewig-modelle

Die Shannon-modelle (shannon-*) besluit in elke versoek self, soos met auto.

Met required of 'n benoemde funksie, lees finish_reason voordat jy tool_calls lees. Wanneer die model geen oproep maak nie, is die antwoord 'n teksantwoord met finish_reason: "stop".

Betekenis /v1/chat/completions /v1/responses /v1/messages
Die model besluit "auto" "auto" {"type": "auto"}
Roep minstens een gereedskap "required" "required" {"type": "any"}
Roep een benoemde funksie {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Aanvaar vir versoenbaarheid: tool_choice: "none" en parallel_tool_calls. Vir 'n beurt sonder gereedskapoproepe, stuur die versoek sonder tools.

Gereedskapoproepe in die antwoord

Veld Tipe Beskrywing
finish_reason string tool_calls wanneer die antwoord minstens een oproep bevat.
message.tool_calls array Een inskrywing per oproep. Die veld is net teenwoordig wanneer die model vir 'n oproep gevra het.
tool_calls[].id string call_ gevolg deur 32 heksadesimale karakters. Stuur dit saam met die resultaat terug as tool_call_id.
tool_calls[].type string Altyd function.
tool_calls[].function.name string Die funksie wat uitgevoer moet word.
tool_calls[].function.arguments string Die argumente as 'n JSON-string, "{}" wanneer daar geen is nie. Ontleed dit voor gebruik.
message.content string | null null wanneer die antwoord slegs oproepe bevat. Die gehuisveste oopgewig-modelle kan teks langs die oproepe teruggee; die Shannon-modelle gee null terug.

Dieselfde oproep in elke formaat. Op /v1/responses is dit 'n function_call-item van output, met arguments as 'n JSON-string. Op /v1/messages is dit 'n tool_use-inhoudblok waarvan input 'n JSON-objek is, sy id met toolu_ begin, en stop_reason tool_use is.

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

Verskeie oproepe in een beurt

'n Antwoord kan verskeie oproepe dra. Voer elkeen daarvan uit en stuur in die volgende versoek een resultaat per oproep, elk met sy eie tool_call_id.

Die gehuisveste oopgewig-modelle gee elke afsonderlike oproep een keer terug: twee oproepe met dieselfde naam en dieselfde argumente kom as een aan.

Gestroomde gereedskapoproepe

Met stream: true kom 'n oproep in een stuk aan: die chunk hou die volledige arguments-string, so daar is geen fragmente om saam te voeg nie. index tel die oproepe van die beurt vanaf 0.

data: een chunk, geformateer
{
  "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
    }
  ]
}
Eindpunt Wat aankom
/v1/chat/completions Een chat.completion.chunk per oproep, met die oproep in delta.tool_calls[0]. Die laaste chunk het finish_reason: "tool_calls" en usage.
/v1/responses Per oproep: response.output_item.added ('n function_call-item met leë arguments), response.function_call_arguments.delta (die hele string), response.function_call_arguments.done, response.output_item.done.
/v1/messages Per oproep: content_block_start ('n tool_use-blok met leë input), een content_block_delta waarvan input_json_delta.partial_json die hele argumenteteks is, content_block_stop. message_delta dra dan stop_reason: "tool_use".

Op shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro en shannon-coder-1 lewer 'n gestroomde versoek wat tools dra sy antwoordteks in een content-delta aan die einde van die beurt. Stroming

Resultate terugstuur

Die tweede versoek herhaal die gesprek en voeg twee dinge by: die assistent-beurt wat vir die oproepe gevra het, en een resultaat per oproep.

{
  "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\"}"
    }
  ]
}
  • Stuur die assistent-beurt terug soos jy dit ontvang het, voor die resultate. Elke resultaat word by sy oproep gepas deur die id: tool_call_id op /v1/chat/completions, call_id op /v1/responses, tool_use_id op /v1/messages.
  • 'n Resultaat is teks. Serialiseer 'n objek na 'n JSON-string vir content (output op /v1/responses). Op /v1/messages is die content van 'n tool_result-blok 'n string of 'n lys teksblokke.
  • In die assistent-beurt bly function.arguments 'n JSON-string, presies soos dit aangekom het.
  • Die gesprek mag met 'n gereedskapresultaat eindig. Geen nuwe gebruikersboodskap is nodig nie: die model gaan voort vanaf die resultaat.
  • Wanneer jou funksie misluk, stuur die mislukking as die resultaatteks. Die model kan dit dan rapporteer of vir 'n ander oproep vra.

Skema-sleutelwoorde

parameters (input_schema op /v1/messages) is 'n JSON Schema. Die Shannon 3-familie (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) en die gehuisveste oopgewig-modelle ontvang dit soos jy dit stuur.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro en shannon-coder-1 ontvang hierdie substel, op al drie eindpunte:

Hantering Sleutelwoorde
Gelees soos gestuur Elke sleutelwoord wat nie in die rye hieronder genoem word nie, byvoorbeeld type, properties, required, items, enum, description, minimum, maximum, anyOf en allOf, op elke vlak van die skema.
format Gelees vir die waardes int32, int64, float, double, byte, date, date-time en enum.
oneOf Gelees as anyOf.
Nie deel van die skema wat hierdie modelle ontvang nie $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 en exclusiveMaximum wanneer hulle getalle is; ander waardes van format.

Gedrag en perke

  • Die API stel geen maksimum getal gereedskap en geen maksimum getal rondtes nie.
  • 'n Versoekliggaam kan tot 32 MiB wees, en die gesprek met sy resultate moet in die konteksvenster van die model pas.
  • Wanneer 'n versoek tools dra, gebruik shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite en shannon-2-pro 'n verstek-temperature van 0.2. Stuur temperature om 'n ander waarde te stel.
  • Elke rondte is 'n versoek op sy eie: dit trek van jou balans af en tel soos enige ander versoek vir vloedbeskerming. Perke en balans

Foute

'n Gereedskapoproep is 'n gewone antwoord met status 200. Hierdie foute gaan oor die versoek self:

Status Tipe Boodskap Wanneer
400 invalid_request_error unknown model: <id> model is nie 'n id uit die gepubliseerde lys nie.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools is nie 'n skikking nie, of 'n ander veld het die verkeerde JSON-tipe.
413 invalid_request_error Failed to buffer the request body: … Die versoekliggaam is groter as 32 MiB. Die fout dra code: "request_too_large".

Die model skryf die argumente. Toets dit teen jou skema voordat jy die funksie uitvoer, soos jy enige invoer van buite sou toets.

Verifikasie-, balans- en bedienerfoute is dieselfde as vir elke versoek. Fouthantering