కంటెంట్‌కు వెళ్లండి
ఫంక్షన్ కాలింగ్

ఫంక్షన్ కాలింగ్

రిక్వెస్ట్‌లో మీ ఫంక్షన్‌లను వివరించండి, మోడల్ తాను చేయించాలనుకున్న కాల్స్‌తో సమాధానం ఇస్తుంది. మీ కోడ్ వాటిని నడిపి ఫలితాలను తిరిగి పంపుతుంది: 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 ను parse చేసి మీ ఫంక్షన్‌ను నడపండి.
4 మీరు assistant మెసేజ్‌ను మరియు ప్రతి కాల్‌కు ఒక tool మెసేజ్‌ను messages కు జోడించి, అదే tools తో రిక్వెస్ట్‌ను మళ్ళీ పంపండి.
5 మోడల్ మోడల్ finish_reason: "stop" తో టెక్స్ట్‌లో సమాధానం ఇస్తుంది, లేదా మరిన్ని కాల్స్ అడుగుతుంది. ఆ సందర్భంలో 3వ దశకు తిరిగి వెళ్లండి.

ఒక రిక్వెస్ట్ అంటే మోడల్ యొక్క ఒక టర్న్. API రిక్వెస్ట్‌ల మధ్య సంభాషణను ఉంచదు మరియు రౌండ్ల సంఖ్యను నిర్ణయించదు: మీ కోడ్ messages ను ఉంచుకుని ఎప్పుడు ఆపాలో నిర్ణయిస్తుంది.

టూల్స్‌ను నిర్వచించడం

tools ప్రతి ఫంక్షన్‌కు ఒక ఎంట్రీ ఉన్న array. కేటలాగ్‌లోని ప్రతి మోడల్ దీన్ని అంగీకరిస్తుంది; GET /v1/models ప్రతి id కి capabilities.tools: true ను నివేదిస్తుంది.

ఫీల్డ్ రకం వివరణ
type string ఎల్లప్పుడూ function.
function.name string మోడల్ ఈ ఫంక్షన్‌ను అడిగేటప్పుడు ఉపయోగించే పేరు. తప్పనిసరి.
function.description string ఫంక్షన్ ఏమి చేస్తుంది, సరళమైన భాషలో.
function.parameters object పైన type: "object" ఉన్న JSON Schema గా ఆర్గ్యుమెంట్‌లు. దిగువన Schema కీవర్డ్‌లు చూడండి.

ప్రతి ఎండ్‌పాయింట్‌కు టూల్ కోసం తన సొంత రూపం ఉంది. మీరు కాల్ చేసే ఎండ్‌పాయింట్‌కు చెందినదాన్ని పంపండి:

{
  "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" సమాధానం కనీసం ఒక టూల్‌ను కాల్ చేస్తుంది. హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్
{"type": "function", "function": {"name": "get_weather"}} సమాధానం ఈ ఫంక్షన్‌ను కాల్ చేస్తుంది. పేరు తప్పనిసరిగా tools లోని ఫంక్షన్‌లలో ఒకటి అయి ఉండాలి. ఇతర ఫంక్షన్‌లకు కాల్స్ సమాధానంలో చేర్చబడవు. హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్

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 string గా, ఏవీ లేనప్పుడు "{}". ఉపయోగించే ముందు దాన్ని parse చేయండి.
message.content string | null సమాధానంలో కాల్స్ మాత్రమే ఉన్నప్పుడు null. హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్ కాల్స్ పక్కన టెక్స్ట్‌ను తిరిగి ఇవ్వగలవు; Shannon మోడల్స్ null ను తిరిగి ఇస్తాయి.

ప్రతి ఫార్మాట్‌లో అదే కాల్. /v1/responses లో ఇది output లోని function_call ఐటెమ్, arguments JSON string గా. /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 తో పంపండి.

హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్ ప్రతి విభిన్న కాల్‌ను ఒకసారి తిరిగి ఇస్తాయి: ఒకే పేరు మరియు ఒకే ఆర్గ్యుమెంట్‌లతో ఉన్న రెండు కాల్స్ ఒకటిగా వస్తాయి.

స్ట్రీమ్ చేసిన టూల్ కాల్స్

stream: true తో, కాల్ ఒకే ముక్కగా వస్తుంది: చంక్‌లో పూర్తి arguments string ఉంటుంది, కాబట్టి కలపాల్సిన ముక్కలు ఉండవు. 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
    }
  ]
}
ఎండ్‌పాయింట్ ఏమి వస్తుంది
/v1/chat/completions ప్రతి కాల్‌కు ఒక chat.completion.chunk, కాల్ delta.tool_calls[0] లో. చివరి చంక్‌లో finish_reason: "tool_calls" మరియు usage ఉంటాయి.
/v1/responses ప్రతి కాల్‌కు: response.output_item.added (ఖాళీ arguments ఉన్న function_call ఐటెమ్), response.function_call_arguments.delta (మొత్తం string), response.function_call_arguments.done, response.output_item.done.
/v1/messages ప్రతి కాల్‌కు: content_block_start (ఖాళీ input ఉన్న tool_use బ్లాక్), ఒక 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 డెల్టాలో అందిస్తుంది. స్ట్రీమింగ్

ఫలితాలను తిరిగి పంపడం

రెండవ రిక్వెస్ట్ సంభాషణను పునరావృతం చేసి రెండు విషయాలను జోడిస్తుంది: కాల్స్ అడిగిన 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 ద్వారా సరిపోలుతుంది: /v1/chat/completions లో tool_call_id, /v1/responses లో call_id, /v1/messages లో tool_use_id.
  • ఫలితం టెక్స్ట్. ఆబ్జెక్ట్‌ను content కోసం (/v1/responses లో output) JSON string గా సీరియలైజ్ చేయండి. /v1/messages లో tool_result బ్లాక్ యొక్క content ఒక string లేదా టెక్స్ట్ బ్లాక్‌ల జాబితా.
  • assistant టర్న్‌లో, function.arguments వచ్చినట్లే JSON string గా ఉంటుంది.
  • సంభాషణ టూల్ ఫలితంతో ముగియవచ్చు. కొత్త user మెసేజ్ అవసరం లేదు: మోడల్ ఫలితం నుండి కొనసాగుతుంది.
  • మీ ఫంక్షన్ విఫలమైనప్పుడు, వైఫల్యాన్ని ఫలిత టెక్స్ట్‌గా పంపండి. అప్పుడు మోడల్ దాన్ని నివేదించవచ్చు లేదా మరో కాల్ అడగవచ్చు.

Schema కీవర్డ్‌లు

parameters (/v1/messages లో input_schema) ఒక JSON Schema. Shannon 3 ఫ్యామిలీ (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) మరియు హోస్ట్ చేసిన ఓపెన్-వెయిట్ మోడల్స్ దాన్ని మీరు పంపినట్లే అందుకుంటాయి.

shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro మరియు shannon-coder-1 మూడు ఎండ్‌పాయింట్‌లలోనూ ఈ ఉపసమితిని అందుకుంటాయి:

నిర్వహణ కీవర్డ్‌లు
పంపినట్లే చదవబడతాయి దిగువ వరుసలలో పేర్కొనని ప్రతి కీవర్డ్, ఉదాహరణకు 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 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 array కాదు, లేదా మరో ఫీల్డ్‌కు తప్పు JSON రకం ఉంది.
413 invalid_request_error Failed to buffer the request body: … రిక్వెస్ట్ బాడీ 32 MiB కంటే పెద్దది. ఎరర్‌లో code: "request_too_large" ఉంటుంది.

ఆర్గ్యుమెంట్‌లను మోడల్ రాస్తుంది. ఏ బయటి ఇన్‌పుట్‌నైనా తనిఖీ చేసినట్లే, ఫంక్షన్‌ను నడిపే ముందు వాటిని మీ schema తో తనిఖీ చేయండి.

ఆథెంటికేషన్, బ్యాలెన్స్ మరియు సర్వర్ ఎరర్‌లు ప్రతి రిక్వెస్ట్‌కు ఉన్నవే. ఎరర్ హ్యాండ్లింగ్