Гузариш ба мундариҷа
Даъвати функсия

Даъвати функсия

Функсияҳои худро дар дархост тавсиф кунед ва модел бо даъватҳое ҷавоб медиҳад, ки мехоҳад иҷро шаванд. Коди шумо онҳоро иҷро мекунад ва натиҷаҳоро бармегардонад: 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 Шумо arguments-и ҳар даъватро таҳлил кунед ва функсияи худро иҷро кунед.
4 Шумо Паёми assistant ва як паёми tool барои ҳар даъватро ба messages илова кунед, баъд дархостро бо ҳамон 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" Ҷавоб ақаллан як абзорро даъват мекунад. Моделҳои open-weight-и хостшуда
{"type": "function", "function": {"name": "get_weather"}} Ҷавоб ин функсияро даъват мекунад. Ном бояд яке аз функсияҳои tools бошад. Даъватҳо ба функсияҳои дигар аз ҷавоб хориҷ карда мешаванд. Моделҳои 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, "{}" вақте ки онҳо нестанд. Пеш аз истифода онро таҳлил кунед.
message.content string | null null вақте ки ҷавоб танҳо даъватҳоро дорад. Моделҳои 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-и худ, дар дархости навбатӣ фиристед.

Моделҳои open-weight-и хостшуда ҳар даъвати фарқкунандаро як бор бармегардонанд: ду даъват бо ҳамон ном ва ҳамон аргументҳо ҳамчун як даъват меоянд.

Даъватҳои абзор дар ҷараён

Бо stream: true даъват як пора меояд: чанк сатри пурраи arguments-ро дорад, бинобар ин порчаҳое нест, ки пайваст кардан лозим бошад. index даъватҳои навбатро аз 0 мешуморад.

data: як чанк, форматшуда
{
  "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]. Чанки охирин 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 дархости streaming, ки tools-ро дорад, матни ҷавобашро дар як delta-и content дар охири навбат мерасонад. Стриминг

Баргардонидани натиҷаҳо

Дархости дуюм гуфтугӯро такрор мекунад ва ду чизро илова мекунад: навбати 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 content-и блоки tool_result сатр ё рӯйхати блокҳои матнӣ аст.
  • Дар навбати assistant function.arguments сатри JSON мемонад, дақиқан ҳамон тавр ки омад.
  • Гуфтугӯ метавонад бо натиҷаи абзор анҷом ёбад. Паёми нави корбар лозим нест: модел аз натиҷа идома медиҳад.
  • Вақте ки функсияи шумо ноком мешавад, нокомиро ҳамчун матни натиҷа фиристед. Он гоҳ модел метавонад онро хабар диҳад ё даъвати дигар хоҳад.

Калидвожаҳои схема

parameters (input_schema дар /v1/messages) JSON Schema аст. Оилаи Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) ва моделҳои 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 ҳадди ақсари шумораи абзорҳо ва ҳадди ақсари шумораи даврҳоро муқаррар намекунад.
  • Бадани дархост то 32 MiB шуда метавонад ва гуфтугӯ бо натиҷаҳояш бояд ба равзанаи контексти модел ҷо шавад.
  • Вақте ки дархост tools-ро дорад, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite ва shannon-2-pro temperature-и пешфарзи 0.2-ро истифода мебаранд. Барои муқаррар кардани қимати дигар temperature-ро фиристед.
  • Ҳар давр дархости алоҳида аст: он аз балансатон сарф мекунад ва мисли ҳар дархости дигар ба ҳифз аз дархостҳои аз ҳад зиёд ҳисоб мешавад. Маҳдудиятҳо ва баланс

Хатогиҳо

Даъвати абзор ҷавоби муқаррарӣ бо ҳолати 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"-ро дорад.

Аргументҳоро модел менависад. Онҳоро пеш аз иҷрои функсия бо схемаи худ санҷед, мисли ҳар вурудии берунӣ.

Хатогиҳои аутентификатсия, баланс ва сервер мисли ҳар дархост ҳамонанданд. Идораи хатогиҳо