Kontentga o'tish
Funksiya chaqirish

Funksiya chaqirish

Funksiyalaringizni so'rovda tasvirlang va model bajarilishini istagan chaqiruvlar bilan javob beradi. Kodingiz ularni bajaradi va natijalarni qaytaradi: API tool chaqiruvlarini qaytaradi va tool'ni o'zi bajarmaydi.

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

Bu sahifadagi namunalar /v1/chat/completionsdan foydalanadi. Xuddi shu sikl /v1/responses va /v1/messages da ham ishlaydi; format biror narsani boshqacha yozsa, quyidagi bo'limlarda uchalasi ham ko'rsatilgan.

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)

Birinchi javob savolga javob bermaydi. U chaqiruvni so'raydi:

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

Natijani yuborganingizdan so'ng keyingi javob oddiy javob bo'ladi: message.content matnni o'z ichiga oladi va finish_reason stop.

Sikl, qadamma-qadam

Qadam Kim Nima bo'ladi
1 Siz messagesni tools bilan birga yuboring, bu model so'rashi mumkin bo'lgan funksiyalar ro'yxati.
2 Model Javob tool_calls va finish_reason: "tool_calls"ni olib keladi. Har bir chaqiruv funksiyani nomlaydi va argumentlarini beradi.
3 Siz Har bir chaqiruvning argumentsini parse qiling va funksiyangizni bajaring.
4 Siz Assistant xabarini va har bir chaqiruv uchun bitta tool xabarini messagesga qo'shing, so'ng so'rovni o'sha tools bilan qayta yuboring.
5 Model Model finish_reason: "stop" bilan matnda javob beradi yoki yana chaqiruvlar so'raydi. Bu holda 3-qadamga qayting.

Bitta so'rov — modelning bitta navbati. API so'rovlar orasida suhbatni saqlamaydi va raundlar sonini belgilamaydi: messagesni kodingiz saqlaydi va qachon to'xtashni hal qiladi.

Tool'larni belgilash

tools — har bir funksiyaga bitta elementli massiv. Katalogdagi har bir model uni qabul qiladi; GET /v1/models har bir id uchun capabilities.tools: trueni ko'rsatadi.

Maydon Tur Tavsif
type string Doim function.
function.name string Model bu funksiyani so'raganda ishlatadigan nom. Majburiy.
function.description string Funksiya nima qiladi, oddiy tilda.
function.parameters object Argumentlar yuqorida type: "object" bo'lgan JSON Schema sifatida. Quyida Sxema kalit so'zlariga qarang.

Har bir endpointning tool yozilishi o'ziniki. Chaqirayotgan endpointingizga tegishlisini yuboring:

{
  "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 modelning tool chaqirishi mumkinmi yoki shartmi, shuni aytadi. U faqat tools bilan birga o'qiladi.

Qiymat Tavsif Qo'llaydi
"auto" Model matn bilan javob berish yoki tool chaqirishni o'zi hal qiladi. Bu standart. Barcha modellar
"required" Javob kamida bitta tool chaqiradi. Xostingdagi open-weight modellar
{"type": "function", "function": {"name": "get_weather"}} Javob shu funksiyani chaqiradi. Nom toolsdagi funksiyalardan biri bo'lishi kerak. Boshqa funksiyalarga chaqiruvlar javobga kiritilmaydi. Xostingdagi open-weight modellar

Shannon modellari (shannon-*) har bir so'rovda autodagidek o'zi hal qiladi.

required yoki nomlangan funksiya bilan tool_callsni o'qishdan oldin finish_reasonni o'qing. Model chaqiruv hosil qilmasa, javob finish_reason: "stop" bilan matnli javob bo'ladi.

Ma'nosi /v1/chat/completions /v1/responses /v1/messages
Model o'zi hal qiladi "auto" "auto" {"type": "auto"}
Kamida bitta tool chaqirish "required" "required" {"type": "any"}
Bitta nomlangan funksiyani chaqirish {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Moslik uchun qabul qilinadi: tool_choice: "none" va parallel_tool_calls. Tool chaqiruvlarisiz navbat uchun so'rovni toolssiz yuboring.

Javobdagi tool chaqiruvlari

Maydon Tur Tavsif
finish_reason string Javobda kamida bitta chaqiruv bo'lsa tool_calls.
message.tool_calls array Har bir chaqiruvga bitta element. Maydon faqat model chaqiruv so'raganda bo'ladi.
tool_calls[].id string call_ va undan keyin 32 ta o'n oltilik belgi. Natija bilan birga uni tool_call_id sifatida qaytaring.
tool_calls[].type string Doim function.
tool_calls[].function.name string Bajariladigan funksiya.
tool_calls[].function.arguments string Argumentlar JSON satri sifatida, yo'q bo'lsa "{}". Ishlatishdan oldin uni parse qiling.
message.content string | null Javobda faqat chaqiruvlar bo'lsa null. Xostingdagi open-weight modellar chaqiruvlar yonida matn qaytarishi mumkin; Shannon modellari null qaytaradi.

Xuddi shu chaqiruv har bir formatda. /v1/responses da u outputning function_call elementi, arguments JSON satri sifatida. /v1/messages da u inputi JSON obyekti bo'lgan tool_use kontent bloki, uning idsi toolu_ bilan boshlanadi va 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\"}"
        }
      }
    ]
  }
}

Bir navbatda bir nechta chaqiruv

Javob bir nechta chaqiruvni olib kelishi mumkin. Ularning hammasini bajaring va keyingi so'rovda har biri o'z tool_call_idsi bilan har bir chaqiruv uchun bitta natija yuboring.

Xostingdagi open-weight modellar har bir alohida chaqiruvni bir marta qaytaradi: nomi va argumentlari bir xil ikki chaqiruv bitta bo'lib keladi.

Oqimli tool chaqiruvlari

stream: true bilan chaqiruv bir butun bo'lib keladi: chunk to'liq arguments satrini o'z ichiga oladi, shuning uchun birlashtiriladigan bo'laklar yo'q. index navbat chaqiruvlarini 0 dan sanaydi.

data: bitta chunk, formatlangan
{
  "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 Nima keladi
/v1/chat/completions Har bir chaqiruvga bitta chat.completion.chunk, chaqiruv delta.tool_calls[0]da. Oxirgi chunkda finish_reason: "tool_calls" va usage bor.
/v1/responses Har bir chaqiruv uchun: response.output_item.added (bo'sh argumentsli function_call elementi), response.function_call_arguments.delta (butun satr), response.function_call_arguments.done, response.output_item.done.
/v1/messages Har bir chaqiruv uchun: content_block_start (bo'sh inputli tool_use bloki), input_json_delta.partial_jsoni butun argumentlar matni bo'lgan bitta content_block_delta, content_block_stop. Keyin message_delta stop_reason: "tool_use"ni olib keladi.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro va shannon-coder-1 da toolsni olib keladigan oqimli so'rov javob matnini navbat oxirida bitta content deltasida yetkazadi. Oqim

Natijalarni qaytarish

Ikkinchi so'rov suhbatni takrorlaydi va ikki narsa qo'shadi: chaqiruvlarni so'ragan assistant navbati va har bir chaqiruv uchun bitta natija.

{
  "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 navbatini natijalardan oldin olganingizdek qaytaring. Har bir natija o'z chaqiruviga id bo'yicha moslanadi: /v1/chat/completions da tool_call_id, /v1/responses da call_id, /v1/messages da tool_use_id.
  • Natija — matn. Obyektni content uchun (/v1/responses da output) JSON satriga serializatsiya qiling. /v1/messages da tool_result blokining contenti satr yoki matn bloklari ro'yxati.
  • Assistant navbatida function.arguments kelganidek, JSON satri bo'lib qoladi.
  • Suhbat tool natijasi bilan tugashi mumkin. Yangi foydalanuvchi xabari kerak emas: model natijadan davom etadi.
  • Funksiyangiz muvaffaqiyatsiz bo'lsa, nosozlikni natija matni sifatida yuboring. Shunda model uni xabar qilishi yoki boshqa chaqiruv so'rashi mumkin.

Sxema kalit so'zlari

parameters (/v1/messages da input_schema) — JSON Schema. Shannon 3 oilasi (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) va xostingdagi open-weight modellar uni yuborganingizdek oladi.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro va shannon-coder-1 uchala endpointda ham shu qism to'plamni oladi:

Ishlov Kalit so'zlar
Yuborilganidek o'qiladi Quyidagi qatorlarda nomlanmagan har bir kalit so'z, masalan type, properties, required, items, enum, description, minimum, maximum, anyOf va allOf, sxemaning har bir darajasida.
format int32, int64, float, double, byte, date, date-time va enum qiymatlari uchun o'qiladi.
oneOf anyOf sifatida o'qiladi.
Bu modellar oladigan sxemaga kirmaydi $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; son bo'lganda exclusiveMinimum va exclusiveMaximum; formatning boshqa qiymatlari.

Xatti-harakat va limitlar

  • API tool'lar sonining ham, raundlar sonining ham maksimumini belgilamaydi.
  • So'rov tanasi 32 MiB gacha bo'lishi mumkin, natijalari bilan suhbat esa modelning kontekst oynasiga sig'ishi kerak.
  • So'rov toolsni olib kelganda shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite va shannon-2-pro standart temperature 0.2 dan foydalanadi. Boshqa qiymat uchun temperatureni yuboring.
  • Har bir raund o'z so'rovi: u balansingizdan oladi va boshqa so'rov kabi flood himoyasiga hisoblanadi. Limitlar va balans

Xatolar

Tool chaqiruvi 200 holatli oddiy javob. Bu xatolar so'rovning o'ziga tegishli:

Holat Tur Xabar Qachon
400 invalid_request_error unknown model: <id> model e'lon qilingan ro'yxatdagi id emas.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … tools massiv emas yoki boshqa maydon noto'g'ri JSON turida.
413 invalid_request_error Failed to buffer the request body: … So'rov tanasi 32 MiB dan katta. Xatoda code: "request_too_large" bor.

Argumentlarni model yozadi. Funksiyani bajarishdan oldin ularni sxemangizga qarshi tekshiring, har qanday tashqi kirishni tekshirganingizdek.

Autentifikatsiya, balans va server xatolari har bir so'rovdagi bilan bir xil. Xatolarni boshqarish