Leum gun t-susbaint
Call gnìomh

Call gnìomh

Mìnich na functions agad san iarrtas agus freagraidh am modail leis na gairmean a tha e ag iarraidh a dhèanamh. Ruithidh an còd agad iad agus cuiridh e na toraidhean air ais: bheir an API gairmean inneil air ais agus chan eil e fhèin a’ ruith inneal.

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

Bidh na sampaill air an duilleag seo a’ cleachdadh /v1/chat/completions. Ruithidh an aon lùb air /v1/responses agus /v1/messages; far a bheil cruth a’ litreachadh rudeigin eadar-dhealaichte, seallaidh na h-earrannan gu h-ìosal na trì.

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)

Chan eil a’ chiad fhreagairt a’ freagairt na ceist. Tha i ag iarraidh gairm:

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

Às dèidh dhut an toradh a chur, tha an ath fhreagairt na fhreagairt àbhaisteach: tha an teacsa ann an message.content agus is e stop an finish_reason.

An lùb, ceum air cheum

Ceum Cò Dè thachras
1 Thu fhèin Cuir messages còmhla ri tools, liosta nan functions a dh’fhaodas am modail iarraidh.
2 Modail Tha tool_calls agus finish_reason: "tool_calls" sa fhreagairt. Ainmichidh gach gairm function agus bheir i na h-argamaidean aice.
3 Thu fhèin Parsaich na arguments aig gach gairm agus ruith an function agad.
4 Thu fhèin Cuir teachdaireachd an assistant agus aon teachdaireachd tool gach gairm ri messages, an uair sin cuir an t-iarrtas a-rithist leis na h-aon tools.
5 Modail Freagraidh am modail ann an teacsa le finish_reason: "stop", no iarraidh e barrachd ghairmean. Anns a’ chùis sin, till gu ceum 3.

Is e aon iarrtas aon tionndadh modail. Chan eil an API a’ cumail còmhradh eadar iarrtasan agus chan eil e a’ suidheachadh àireamh chuairtean: tha messages aig an chòd agad agus cho-dhùineas e cuin a stadas e.

A’ mìneachadh innealan

Is e array a th’ ann an tools le aon inntrigeadh gach function. Gabhaidh gach modail dhen chatalog ris; bheir GET /v1/models cunntas air capabilities.tools: true airson gach id.

Raon Seòrsa Tuairisgeul
type string An-còmhnaidh function.
function.name string An t-ainm a chleachdas am modail nuair a dh’iarras e an function seo. Riatanach.
function.description string Dè a nì an function, ann am briathran sìmplidh.
function.parameters object Na h-argamaidean mar JSON Schema le type: "object" aig a’ mhullach. Faic Facail-iuchrach schema gu h-ìosal.

Tha litreachadh fhèin aig gach endpoint airson inneal. Cuir am fear a bhuineas dhan endpoint a ghairmeas tu:

{
  "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

Innsidh tool_choice an fhaod am modail, no am feum e, inneal a ghairm. Thèid a leughadh a-mhàin còmhla ri tools.

Luach Tuairisgeul Air a chur an sàs le
"auto" Co-dhùineas am modail an freagair e ann an teacsa no an gairm e inneal. Is e seo a’ bhun-roghainn. A h-uile modail
"required" Gairmidh am freagairt co-dhiù aon inneal. Modailean open-weight hosted
{"type": "function", "function": {"name": "get_weather"}} Gairmidh am freagairt an function seo. Feumaidh an t-ainm a bhith air aon dhe na functions ann an tools. Thèid gairmean gu functions eile fhàgail a-mach às a’ fhreagairt. Modailean open-weight hosted

Co-dhùineas na modailean Shannon (shannon-*) anns gach iarrtas, mar le auto.

Le required no function ainmichte, leugh finish_reason mus leugh thu tool_calls. Mura toir am modail gairm, tha am freagairt na fhreagairt teacsa le finish_reason: "stop".

Brìgh /v1/chat/completions /v1/responses /v1/messages
Co-dhùineas am modail "auto" "auto" {"type": "auto"}
Gairm co-dhiù aon inneal "required" "required" {"type": "any"}
Gairm aon function ainmichte {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Air aontachadh airson co-chòrdalachd: tool_choice: "none" agus parallel_tool_calls. Airson tionndadh gun ghairmean inneil, cuir an t-iarrtas gun tools.

Gairmean inneil san fhreagairt

Raon Seòrsa Tuairisgeul
finish_reason string tool_calls nuair a tha co-dhiù aon ghairm san fhreagairt.
message.tool_calls array Aon inntrigeadh gach gairm. Tha an raon an làthair a-mhàin nuair a dh’iarr am modail gairm.
tool_calls[].id string call_ agus an uair sin 32 caractar sia-deugach. Cuir air ais e mar tool_call_id leis an toradh.
tool_calls[].type string An-còmhnaidh function.
tool_calls[].function.name string An function ri ruith.
tool_calls[].function.arguments string Na h-argamaidean mar shreang JSON, "{}" nuair nach eil gin ann. Parsaich e mus cleachd thu e.
message.content string | null null nuair nach eil ach gairmean san fhreagairt. Faodaidh na modailean open-weight hosted teacsa a thilleadh ri taobh nan gairmean; tillidh na modailean Shannon null.

An aon ghairm anns gach cruth. Air /v1/responses is e nì function_call de output a th’ ann, le arguments mar shreang JSON. Air /v1/messages is e bloc susbaint tool_use a th’ ann aig a bheil input na nì JSON, tòisichidh id le toolu_, agus is e tool_use an stop_reason.

{
  "finish_reason": "tool_calls",
  "message": {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_9f1c2ab34d5e4f60a7b8c9d0e1f2a3b4",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"Paris\"}"
        }
      }
    ]
  }
}

Grunn ghairmean ann an aon tionndadh

Faodaidh grunn ghairmean a bhith ann am freagairt. Ruith gach tè dhiubh agus cuir aon toradh gach gairm, gach fear len tool_call_id fhèin, san ath iarrtas.

Tillidh na modailean open-weight hosted gach gairm sònraichte aon turas: thig dà ghairm leis an aon ainm agus na h-aon argamaidean mar aon.

Gairmean inneil streamte

Le stream: true, thig gairm na aon phìos: tha an sreang arguments slàn anns a’ chunk, agus mar sin chan eil criomagan ri cheangal. Cunntaidh index gairmean an tionndaidh o 0.

data: aon chunk, air a fhòrmatadh
{
  "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 Dè a thig
/v1/chat/completions Aon chat.completion.chunk gach gairm, leis a’ ghairm ann an delta.tool_calls[0]. Tha finish_reason: "tool_calls" agus usage aig an chunk mu dheireadh.
/v1/responses Gach gairm: response.output_item.added (nì function_call le arguments falamh), response.function_call_arguments.delta (an sreang slàn), response.function_call_arguments.done, response.output_item.done.
/v1/messages Gach gairm: content_block_start (bloc tool_use le input falamh), aon content_block_delta aig a bheil input_json_delta.partial_json mar an teacsa argamaidean slàn, content_block_stop. An uair sin bidh stop_reason: "tool_use" aig message_delta.

Air shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro agus shannon-coder-1, lìbhrigidh iarrtas streamte a bheir tools teacsa a fhreagairt ann an aon delta content aig deireadh an tionndaidh. Sruthadh

A’ cur thoraidhean air ais

Ath-aithnichidh an dàrna iarrtas an còmhradh agus cuiridh e dà rud ris: tionndadh an assistant a dh’iarr na gairmean, agus aon toradh gach gairm.

{
  "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\"}"
    }
  ]
}
  • Cuir tionndadh an assistant air ais mar a fhuair thu e, ron toraidhean. Thèid gach toradh a mhaidseadh ris a’ ghairm aige le id: tool_call_id air /v1/chat/completions, call_id air /v1/responses, tool_use_id air /v1/messages.
  • Is e teacsa a th’ ann an toradh. Dèan sreang JSON de nì airson content (output air /v1/responses). Air /v1/messages is e sreang no liosta de bhlocaichean teacsa content bloc tool_result.
  • Ann an tionndadh an assistant, fanaidh function.arguments na shreang JSON, dìreach mar a thàinig e.
  • Faodaidh an còmhradh crìochnachadh le toradh inneil. Chan eil feum air teachdaireachd ùr neach-cleachdaidh: leanaidh am modail on toradh.
  • Nuair a dh’fhailicheas an function agad, cuir am fàilligeadh mar theacsa an toraidh. Faodaidh am modail aithris air no gairm eile iarraidh an uair sin.

Facail-iuchrach schema

Is e JSON Schema parameters (input_schema air /v1/messages). Gheibh teaghlach Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) agus na modailean open-weight hosted e mar a chuireas tu e.

Gheibh shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro agus shannon-coder-1 am fo-sheata seo, air na trì endpoints:

Làimhseachadh Facail-iuchrach
Air a leughadh mar a chaidh a chur A h-uile facal-iuchrach nach eil air ainmeachadh anns na sreathan gu h-ìosal, mar eisimpleir type, properties, required, items, enum, description, minimum, maximum, anyOf agus allOf, aig gach ìre dhen schema.
format Air a leughadh airson na luachan int32, int64, float, double, byte, date, date-time agus enum.
oneOf Air a leughadh mar anyOf.
Chan eil pàirt dhen schema a gheibh na modailean seo $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 agus exclusiveMaximum nuair as e àireamhan a th’ annta; luachan eile de format.

Giùlan agus crìochan

  • Chan eil an API a’ suidheachadh uas-àireamh innealan no uas-àireamh chuairtean.
  • Faodaidh bodhaig iarrtais a bhith suas gu 32 MiB, agus feumaidh an còmhradh leis na toraidhean aige a bhith a’ freagairt ri uinneag cho-theacsa a’ mhodail.
  • Nuair a bhios tools aig iarrtas, cleachdaidh shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite agus shannon-2-pro temperature bun-roghainn 0.2. Cuir temperature gus luach eile a shuidheachadh.
  • Tha gach cuairt na iarrtas fa leth: tarraingidh e às do bhalance agus thèid a chunntadh airson dìon thar-thuiltidh mar iarrtas sam bith eile. Crìochan agus balance

Mearachdan

Tha gairm inneil na freagairt àbhaisteach le staid 200. Buinidh na mearachdan seo ris an iarrtas fhèin:

Staid Seòrsa Teachdaireachd Cuin
400 invalid_request_error unknown model: <id> Chan e id air an liosta fhoillsichte a th’ ann an model.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Chan e array a th’ ann an tools, no tha seòrsa JSON ceàrr air raon eile.
413 invalid_request_error Failed to buffer the request body: … Tha bodhaig an iarrtais nas motha na 32 MiB. Tha code: "request_too_large" sa mhearachd.

Sgrìobhaidh am modail na h-argamaidean. Dearbh iad an aghaidh do schema mus ruith thu an function, mar a dhearbhadh tu input sam bith o‘n taobh a-muigh.

Tha mearachdan dearbhaidh, balance agus server mar a tha iad airson gach iarrtas. Làimhseachadh mearachd