Fara í efni
Aðgerðaköll

Aðgerðaköll

Lýstu föllunum þínum í beiðninni og líkanið svarar með köllunum sem það vill láta gera. Kóðinn þinn keyrir þau og sendir niðurstöðurnar til baka: API skilar tólakölum og keyrir ekkert tól sjálft.

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

Dæmin á þessari síðu nota /v1/chat/completions. Sama lykkja keyrir á /v1/responses og /v1/messages; þar sem snið skrifar eitthvað öðruvísi sýna kaflarnir hér á eftir öll þrjú.

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)

Fyrsta svarið svarar ekki spurningunni. Það biður um kall:

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

Eftir að þú sendir niðurstöðuna er næsta svar venjulegt svar: message.content geymir textann og finish_reason er stop.

Lykkjan, skref fyrir skref

Skref Hver Hvað gerist
1 Þú Sendu messages ásamt tools, listanum yfir föllin sem líkanið má biðja um.
2 Líkan Svarið ber tool_calls og finish_reason: "tool_calls". Hvert kall nefnir fall og gefur röksemdir þess.
3 Þú Þáttaðu arguments hvers kalls og keyrðu fallið þitt.
4 Þú Bættu assistant-skilaboðunum og einum tool skilaboðum á kall við messages og sendu síðan beiðnina aftur með sömu tools.
5 Líkan Líkanið svarar með texta og finish_reason: "stop", eða biður um fleiri köll. Farðu í því tilviki aftur í skref 3.

Ein beiðni er ein lota líkansins. API geymir ekkert samtal milli beiðna og setur engan fjölda umferða: kóðinn þinn heldur messages og ákveður hvenær á að hætta.

Tól skilgreind

tools er fylki með eina færslu á fall. Öll líkön í skránni taka við því; GET /v1/models sýnir capabilities.tools: true fyrir hvert auðkenni.

Reitur Gerð Lýsing
type string Alltaf function.
function.name string Heitið sem líkanið notar þegar það biður um þetta fall. Skylda.
function.description string Hvað fallið gerir, á einföldu máli.
function.parameters object Röksemdirnar sem JSON Schema með type: "object" efst. Sjá Lykilorð skema hér á eftir.

Hver endapunktur hefur sína eigin ritun tóls. Sendu þá sem tilheyrir endapunktinum sem þú kallar á:

{
  "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 segir hvort líkanið megi, eða verði, að kalla á tól. Það er aðeins lesið ásamt tools.

Gildi Lýsing Notað af
"auto" Líkanið ákveður hvort það svarar með texta eða kallar á tól. Þetta er sjálfgefið. Öll líkön
"required" Svarið kallar á að minnsta kosti eitt tól. Hýst líkön með opnum þyngdum
{"type": "function", "function": {"name": "get_weather"}} Svarið kallar á þetta fall. Heitið verður að vera eitt af föllunum í tools. Köll á önnur föll eru undanskilin svarinu. Hýst líkön með opnum þyngdum

Shannon-líkönin (shannon-*) ákveða í hverri beiðni, eins og með auto.

Með required eða nefndu falli skaltu lesa finish_reason áður en þú lest tool_calls. Þegar líkanið gerir ekkert kall er svarið textasvar með finish_reason: "stop".

Merking /v1/chat/completions /v1/responses /v1/messages
Líkanið ákveður "auto" "auto" {"type": "auto"}
Kalla á að minnsta kosti eitt tól "required" "required" {"type": "any"}
Kalla á eitt nefnt fall {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Samþykkt vegna samhæfni: tool_choice: "none" og parallel_tool_calls. Fyrir lotu án tólakalla skaltu senda beiðnina án tools.

Tólakall í svarinu

Reitur Gerð Lýsing
finish_reason string tool_calls þegar svarið ber að minnsta kosti eitt kall.
message.tool_calls array Ein færsla á kall. Reiturinn er aðeins til staðar þegar líkanið bað um kall.
tool_calls[].id string call_ og síðan 32 sextándakerfisstafir. Sendu það til baka sem tool_call_id með niðurstöðunni.
tool_calls[].type string Alltaf function.
tool_calls[].function.name string Fallið sem á að keyra.
tool_calls[].function.arguments string Röksemdirnar sem JSON-strengur, "{}" þegar þær eru engar. Þáttaðu hann áður en þú notar hann.
message.content string | null null þegar svarið geymir aðeins köll. Hýst líkön með opnum þyngdum geta skilað texta við hlið kallanna; Shannon-líkönin skila null.

Sama kallið á hverju sniði. Á /v1/responses er það function_call færsla í output, með arguments sem JSON-streng. Á /v1/messages er það tool_use efnisblokk þar sem input er JSON-hlutur, id byrjar á toolu_ og stop_reason er 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\"}"
        }
      }
    ]
  }
}

Mörg köll í einni lotu

Svar getur borið mörg köll. Keyrðu þau öll og sendu eina niðurstöðu fyrir hvert kall, hverja með sínu tool_call_id, í næstu beiðni.

Hýst líkön með opnum þyngdum skila hverju ólíku kalli einu sinni: tvö köll með sama heiti og sömu röksemdir berast sem eitt.

Streymd tólakall

Með stream: true berst kall í einu lagi: búturinn geymir allan arguments strenginn, svo engin brot þarf að tengja saman. index telur köll lotunnar frá 0.

data: einn búttur, sniðinn
{
  "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
    }
  ]
}
Endapunktur Hvað berst
/v1/chat/completions Einn chat.completion.chunk á kall, með kallið í delta.tool_calls[0]. Síðasti búturinn hefur finish_reason: "tool_calls" og usage.
/v1/responses Á kall: response.output_item.added (function_call færsla með tómt arguments), response.function_call_arguments.delta (allur strengurinn), response.function_call_arguments.done, response.output_item.done.
/v1/messages Á kall: content_block_start (tool_use blokk með tómt input), eitt content_block_delta þar sem input_json_delta.partial_json er allur röksemdatextinn, content_block_stop. message_delta ber síðan stop_reason: "tool_use".

Á shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro og shannon-coder-1 skilar streymd beiðni sem ber tools svartextanum í einu content delta í lok lotunnar. Streymi

Niðurstöður sendar til baka

Seinni beiðnin endurtekur samtalið og bætir við tveimur hlutum: assistant-lotunni sem bað um köllin og einni niðurstöðu á kall.

{
  "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\"}"
    }
  ]
}
  • Sendu assistant-lotuna til baka eins og þú fékkst hana, á undan niðurstöðunum. Hver niðurstaða er pöruð við kall sitt með auðkenni: tool_call_id á /v1/chat/completions, call_id á /v1/responses, tool_use_id á /v1/messages.
  • Niðurstaða er texti. Raðaðu hlut í JSON-streng fyrir content (output á /v1/responses). Á /v1/messages er content í tool_result blokk strengur eða listi af textablokkum.
  • Í assistant-lotunni helst function.arguments JSON-strengur, nákvæmlega eins og hann barst.
  • Samtalið má enda á tólaniðurstöðu. Engin ný notandaskilaboð eru nauðsynleg: líkanið heldur áfram frá niðurstöðunni.
  • Þegar fallið þitt mistekst skaltu senda bilunina sem niðurstöðutexta. Líkanið getur þá greint frá henni eða beðið um annað kall.

Lykilorð skema

parameters (input_schema á /v1/messages) er JSON Schema. Shannon 3 fjölskyldan (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) og hýst líkön með opnum þyngdum fá það eins og þú sendir það.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro og shannon-coder-1 fá þessa hlutmengi, á öllum þremur endapunktunum:

Meðferð Lykilorð
Lesið eins og sent Öll lykilorð sem eru ekki nefnd í línunum hér fyrir neðan, til dæmis type, properties, required, items, enum, description, minimum, maximum, anyOf og allOf, á öllum stigum skemans.
format Lesið fyrir gildin int32, int64, float, double, byte, date, date-time og enum.
oneOf Lesið sem anyOf.
Ekki hluti af skemanu sem þessi líkön fá $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 og exclusiveMaximum þegar þau eru tölur; önnur gildi format.

Hegðun og mörk

  • API setur engin hámörk á fjölda tóla og engin hámörk á fjölda umferða.
  • Beiðnameginmál getur verið allt að 32 MiB, og samtalið með niðurstöðum sínum verður að komast fyrir í samhengisglugga líkansins.
  • Þegar beiðni ber tools nota shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite og shannon-2-pro sjálfgefið temperature 0.2. Sendu temperature til að stilla annað gildi.
  • Hver umferð er sjálfstæð beiðni: hún dregur af stöðunni þinni og telst með í flóðvörn eins og hver önnur beiðni. Mörk og staða

Villur

Tólakall er venjulegt svar með stöðuna 200. Þessar villur varða beiðnina sjálfa:

Staða Gerð Skilaboð Hvenær
400 invalid_request_error unknown model: <id> model er ekki auðkenni af útgefna listanum.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools er ekki fylki, eða annar reitur hefur rangt JSON-gagnatag.
413 invalid_request_error Failed to buffer the request body: … Beiðnameginmálið er stærra en 32 MiB. Villan ber code: "request_too_large".

Líkanið skrifar röksemdirnar. Athugaðu þær gegn skemanu þínu áður en þú keyrir fallið, eins og þú athugaðir hvert annað utanaðkomandi inntak.

Auðkenning, staða og þjónsvillur eru þær sömu og fyrir allar beiðnir. Villumeðhöndlun