გადასვლა შინაარსზე
ფუნქციის გამოძახება

ფუნქციის გამოძახება

აღწერეთ თქვენი ფუნქციები მოთხოვნაში და მოდელი გიპასუხებთ გამოძახებებით, რომელთა შესრულებაც სურს. თქვენი კოდი მათ ასრულებს და შედეგებს უკან აგზავნის: 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"-ით. იხილეთ ქვემოთ სქემის საკვანძო სიტყვები.

თითოეულ 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-ზე ის არის function_call ელემენტი output-ში, 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 მოდელები თითოეულ განსხვავებულ გამოძახებას ერთხელ აბრუნებენ: ორი გამოძახება ერთი და იმავე სახელითა და ერთი და იმავე არგუმენტებით ერთად მოდის.

სტრიმული ინსტრუმენტების გამოძახებები

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-ს ატარებს, პასუხის ტექსტს ერთ 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 სტრიქონად, ზუსტად ისე, როგორც მოვიდა.
  • საუბარი შეიძლება ინსტრუმენტის შედეგით დასრულდეს. ახალი user შეტყობინება საჭირო არ არის: მოდელი შედეგიდან აგრძელებს.
  • როცა თქვენი ფუნქცია ვერ სრულდება, წარუმატებლობა შედეგის ტექსტად გააგზავნეთ. მოდელს შემდეგ შეუძლია ამის შესახებ აცნობოს ან სხვა გამოძახება მოითხოვოს.

სქემის საკვანძო სიტყვები

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, სქემის ყველა დონეზე.
format იკითხება მნიშვნელობებისთვის int32, int64, float, double, byte, date, date-time და enum.
oneOf იკითხება როგორც anyOf.
არ შედის სქემაში, რომელსაც ეს მოდელები იღებენ $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 არ ადგენს ინსტრუმენტების მაქსიმალურ რაოდენობას და ტურების მაქსიმალურ რაოდენობას.
  • მოთხოვნის body შეიძლება 32 MiB-მდე იყოს და საუბარი თავისი შედეგებით მოდელის კონტექსტის ფანჯარაში უნდა ეტეოდეს.
  • როცა მოთხოვნა ატარებს tools-ს, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite და shannon-2-pro ნაგულისხმევ temperature-ს 0.2-ს იყენებენ. სხვა მნიშვნელობის დასაყენებლად გააგზავნეთ temperature.
  • ყოველი ტური ცალკე მოთხოვნაა: ის თქვენს ბალანსს ხარჯავს და flood protection-ში ნებისმიერი სხვა მოთხოვნასავით ითვლება. ლიმიტები და ბალანსი

შეცდომები

ინსტრუმენტის გამოძახება ჩვეულებრივი პასუხია სტატუსით 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: … მოთხოვნის body 32 MiB-ზე დიდია. შეცდომა ატარებს code: "request_too_large"-ს.

არგუმენტებს მოდელი წერს. ფუნქციის შესრულებამდე შეამოწმეთ ისინი თქვენი სქემის მიხედვით, ისევე როგორც ნებისმიერ გარე შეტანას.

ავთენტიკაციის, ბალანსისა და სერვერის შეცდომები იგივეა, რაც ნებისმიერი მოთხოვნისთვის. შეცდომების დამუშავება