Անցնել բովանդակությանը
Ֆունկցիայի կանչ

Ֆունկցիայի կանչ

Նկարագրեք ձեր ֆունկցիաները հարցման մեջ, և մոդելը պատասխանում է այն կանչերով, որոնք ցանկանում է կատարել։ Ձեր կոդը կատարում է դրանք և արդյունքները ուղարկում հետ. API-ն վերադարձնում է գործիքների կանչեր և ինքը գործիք չի կատարում։

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

Այս էջի օրինակներն օգտագործում են /v1/chat/completions։ Նույն ցիկլն աշխատում է /v1/responses-ում և /v1/messages-ում. որտեղ ձևաչափերը ինչ-որ բան այլ կերպ են գրում, ստորև բաժինները ցույց են տալիս երեքն էլ։

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)

Առաջին պատասխանը հարցին չի պատասխանում։ Այն կանչ է խնդրում.

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

Արդյունքը ուղարկելուց հետո հաջորդ պատասխանը սովորական պատասխան է. message.content-ը պարունակում է տեքստը, և finish_reason-ը stop է։

Ցիկլը՝ քայլ առ քայլ

Քայլ Ով Ինչ է տեղի ունենում
1 Դուք Ուղարկեք messages՝ tools-ի հետ, այն ֆունկցիաների ցանկը, որոնք մոդելը կարող է խնդրել։
2 Մոդել Պատասխանը կրում է tool_calls և finish_reason: "tool_calls"։ Յուրաքանչյուր կանչ նշում է ֆունկցիան և տալիս նրա արգումենտները։
3 Դուք Վերլուծեք (parse) յուրաքանչյուր կանչի arguments-ը և կատարեք ձեր ֆունկցիան։
4 Դուք messages-ին կցեք assistant հաղորդագրությունը և մեկական tool հաղորդագրություն յուրաքանչյուր կանչի համար, ապա նույն tools-ով կրկին ուղարկեք հարցումը։
5 Մոդել Մոդելը պատասխանում է տեքստով՝ finish_reason: "stop"-ով, կամ խնդրում է նոր կանչեր։ Այդ դեպքում վերադարձեք 3-րդ քայլին։

Մեկ հարցումը մոդելի մեկ փուլ է։ API-ն հարցումների միջև զրույց չի պահում և փուլերի քանակ չի սահմանում. messages-ը պահում է ձեր կոդը և որոշում, թե երբ կանգ առնել։

Գործիքների սահմանում

tools-ը զանգված է՝ մեկ գրառմամբ յուրաքանչյուր ֆունկցիայի համար։ Կատալոգի յուրաքանչյուր մոդել ընդունում է այն. GET /v1/models-ը յուրաքանչյուր id-ի համար ցույց է տալիս capabilities.tools: true։

Դաշտ Տեսակ Նկարագրություն
type string Միշտ function։
function.name string Անունը, որը մոդելն օգտագործում է այս ֆունկցիան խնդրելիս։ Պարտադիր է։
function.description string Ինչ է անում ֆունկցիան՝ պարզ լեզվով։
function.parameters object Արգումենտները որպես JSON Schema՝ վերևում type: "object"-ով։ Տես ստորև Schema-ի բանալի բառեր։

Յուրաքանչյուր endpoint ունի գործիքի իր գրելաձևը։ Ուղարկեք այն, որը պատկանում է ձեր կանչած endpoint-ին.

{
  "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-ը ասում է՝ մոդելը կարող է, թե պարտավոր է գործիք կանչել։ Այն կարդացվում է միայն tools-ի հետ միասին։

Արժեք Նկարագրություն Կիրառվում է
"auto" Մոդելն ինքն է որոշում՝ պատասխանել տեքստով, թե կանչել գործիք։ Սա լռելյայն արժեքն է։ Բոլոր մոդելները
"required" Պատասխանը կանչում է առնվազն մեկ գործիք։ Hosted open-weight մոդելներ
{"type": "function", "function": {"name": "get_weather"}} Պատասխանը կանչում է այս ֆունկցիան։ Անունը պետք է լինի tools-ում եղած ֆունկցիաներից մեկը։ Այլ ֆունկցիաների կանչերը պատասխանից դուրս են թողնվում։ Hosted open-weight մոդելներ

Shannon մոդելները (shannon-*) որոշում են յուրաքանչյուր հարցման մեջ, ինչպես auto-ի դեպքում։

required-ի կամ անվանված ֆունկցիայի դեպքում tool_calls-ը կարդալուց առաջ կարդացեք finish_reason-ը։ Երբ մոդելը կանչ չի ստեղծում, պատասխանը տեքստային է՝ finish_reason: "stop"-ով։

Նշանակություն /v1/chat/completions /v1/responses /v1/messages
Մոդելն ինքն է որոշում "auto" "auto" {"type": "auto"}
Կանչել առնվազն մեկ գործիք "required" "required" {"type": "any"}
Կանչել մեկ անվանված ֆունկցիա {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Ընդունվում են համատեղելիության համար՝ tool_choice: "none" և parallel_tool_calls։ Գործիքի կանչեր չունեցող փուլի համար ուղարկեք հարցումն առանց tools-ի։

Գործիքի կանչերը պատասխանում

Դաշտ Տեսակ Նկարագրություն
finish_reason string tool_calls, երբ պատասխանը կրում է առնվազն մեկ կանչ։
message.tool_calls array Մեկ գրառում յուրաքանչյուր կանչի համար։ Դաշտը առկա է միայն այն դեպքում, երբ մոդելը կանչ է խնդրել։
tool_calls[].id string call_, որին հաջորդում են 32 տասնվեցական նիշ։ Արդյունքի հետ ուղարկեք այն հետ որպես tool_call_id։
tool_calls[].type string Միշտ function։
tool_calls[].function.name string Կատարվելիք ֆունկցիան։
tool_calls[].function.arguments string Արգումենտները որպես JSON տող, "{}", երբ դրանք չկան։ Օգտագործելուց առաջ վերլուծեք (parse) այն։
message.content string | null null, երբ պատասխանը պարունակում է միայն կանչեր։ Hosted open-weight մոդելները կարող են տեքստ վերադարձնել կանչերի կողքին. Shannon մոդելները վերադարձնում են null։

Նույն կանչը յուրաքանչյուր ձևաչափում։ /v1/responses-ում դա output-ի function_call տարր է, որի arguments-ը JSON տող է։ /v1/messages-ում դա tool_use բովանդակության բլոկ է, որի input-ը JSON օբյեկտ է, id-ն սկսվում է toolu_-ով, իսկ stop_reason-ը 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\"}"
        }
      }
    ]
  }
}

Մի քանի կանչ մեկ փուլում

Պատասխանը կարող է կրել մի քանի կանչ։ Կատարեք յուրաքանչյուրը և հաջորդ հարցմանը ուղարկեք մեկական արդյունք յուրաքանչյուր կանչի համար՝ իր tool_call_id-ով։

Hosted open-weight մոդելները յուրաքանչյուր տարբեր կանչը վերադարձնում են մեկ անգամ. նույն անունով և նույն արգումենտներով երկու կանչ գալիս է որպես մեկ։

Streaming գործիքի կանչեր

stream: true-ով կանչը գալիս է մեկ կտորով. chunk-ը պարունակում է arguments ամբողջական տողը, ուստի միացնելու հատվածներ չկան։ index-ը փուլի կանչերը համարակալում է 0-ից։

data. մեկ chunk, ձևաչափված
{
  "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
    }
  ]
}
Endpoint Ինչ է գալիս
/v1/chat/completions Մեկ chat.completion.chunk յուրաքանչյուր կանչի համար, կանչը՝ delta.tool_calls[0]-ում։ Վերջին chunk-ն ունի finish_reason: "tool_calls" և usage։
/v1/responses Յուրաքանչյուր կանչի համար՝ response.output_item.added (function_call տարր դատարկ arguments-ով), response.function_call_arguments.delta (ամբողջ տողը), response.function_call_arguments.done, response.output_item.done։
/v1/messages Յուրաքանչյուր կանչի համար՝ content_block_start (tool_use բլոկ դատարկ input-ով), մեկ content_block_delta, որի input_json_delta.partial_json-ը արգումենտների ամբողջ տեքստն է, content_block_stop։ Ապա message_delta-ն կրում է stop_reason: "tool_use"։

shannon-1.6-lite-ի, shannon-1.6-pro-ի, shannon-2-lite-ի, shannon-2-pro-ի և shannon-coder-1-ի վրա tools կրող streaming հարցումը իր պատասխանի տեքստը տալիս է մեկ content delta-ով՝ փուլի վերջում։ Ստրիմինգ

Արդյունքների ուղարկումը հետ

Երկրորդ հարցումը կրկնում է զրույցը և ավելացնում երկու բան՝ assistant փուլը, որը կանչեր էր խնդրել, և մեկ արդյունք յուրաքանչյուր կանչի համար։

{
  "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\"}"
    }
  ]
}
  • Assistant փուլը արդյունքներից առաջ ուղարկեք հետ այնպես, ինչպես ստացել եք։ Յուրաքանչյուր արդյունք իր կանչին կապվում է id-ով՝ tool_call_id /v1/chat/completions-ում, call_id /v1/responses-ում, tool_use_id /v1/messages-ում։
  • Արդյունքը տեքստ է։ Օբյեկտը սերիալիզացրեք JSON տողի content-ի համար (output /v1/responses-ում)։ /v1/messages-ում tool_result բլոկի content-ը տող է կամ տեքստային բլոկների ցանկ։
  • Assistant փուլում function.arguments-ը մնում է JSON տող՝ ճիշտ այնպես, ինչպես եկել է։
  • Զրույցը կարող է ավարտվել գործիքի արդյունքով։ Նոր օգտատիրոջ հաղորդագրություն պետք չէ. մոդելը շարունակում է արդյունքից։
  • Երբ ձեր ֆունկցիան ձախողվում է, ձախողումն ուղարկեք որպես արդյունքի տեքստ։ Այդ դեպքում մոդելը կարող է հայտնել դրա մասին կամ խնդրել այլ կանչ։

Schema-ի բանալի բառեր

parameters-ը (input_schema /v1/messages-ում) JSON Schema է։ Shannon 3 ընտանիքը (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) և hosted open-weight մոդելները ստանում են այն այնպես, ինչպես ուղարկում եք։

shannon-1.6-lite-ը, shannon-1.6-pro-ն, shannon-2-lite-ը, shannon-2-pro-ն և shannon-coder-1-ը ստանում են այս ենթաբազմությունը՝ երեք endpoint-ներում էլ.

Վերաբերմունք Բանալի բառեր
Կարդացվում է այնպես, ինչպես ուղարկվել է Յուրաքանչյուր բանալի բառ, որը չի նշված ստորև տողերում, օրինակ՝ type, properties, required, items, enum, description, minimum, maximum, anyOf և allOf, schema-ի յուրաքանչյուր մակարդակում։
format Կարդացվում է int32, int64, float, double, byte, date, date-time և enum արժեքների համար։
oneOf Կարդացվում է որպես anyOf։
Այս մոդելների ստացած schema-ի մաս չէ $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 և exclusiveMaximum, երբ դրանք թվեր են. format-ի մյուս արժեքները։

Վարքագիծ և սահմանաչափեր

  • API-ն գործիքների առավելագույն քանակ և փուլերի առավելագույն քանակ չի սահմանում։
  • Հարցման մարմինը կարող է լինել մինչև 32 MiB, և զրույցը՝ արդյունքներով հանդերձ, պետք է տեղավորվի մոդելի համատեքստի պատուհանում։
  • Երբ հարցումը կրում է tools, shannon-1.6-lite-ը, shannon-1.6-pro-ն, shannon-2-lite-ը և shannon-2-pro-ն օգտագործում են temperature-ի լռելյայն 0.2 արժեքը։ Այլ արժեք սահմանելու համար ուղարկեք temperature։
  • Յուրաքանչյուր փուլ առանձին հարցում է. այն ծախսում է ձեր մնացորդից և հաշվվում է flood-պաշտպանության մեջ, ինչպես ցանկացած այլ հարցում։ Սահմանաչափեր և մնացորդ

Սխալներ

Գործիքի կանչը սովորական պատասխան է 200 կարգավիճակով։ Այս սխալները վերաբերում են հենց հարցմանը.

Կարգավիճակ Տեսակ Հաղորդագրություն Երբ
400 invalid_request_error unknown model: <id> model-ը հրապարակված ցանկի id չէ։
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools-ը զանգված չէ, կամ մեկ այլ դաշտ ունի սխալ JSON տեսակ։
413 invalid_request_error Failed to buffer the request body: … Հարցման մարմինը մեծ է 32 MiB-ից։ Սխալը կրում է code: "request_too_large"։

Արգումենտները գրում է մոդելը։ Ստուգեք դրանք ձեր schema-ով՝ ֆունկցիան կատարելուց առաջ, ինչպես ստուգում եք ցանկացած արտաքին մուտք։

Վավերացման, մնացորդի և սերվերի սխալները նույնն են, ինչ յուրաքանչյուր հարցման համար։ Սխալների մշակում