Neidio i'r cynnwys
Galw swyddogaeth

Galw swyddogaeth

Disgrifiwch eich ffwythiannau yn y cais ac mae'r model yn ateb gyda'r galwadau y mae eisiau eu gwneud. Mae eich cod yn eu rhedeg ac yn anfon y canlyniadau yn ôl: mae'r API yn dychwelyd galwadau offer ac nid yw'n rhedeg offeryn ei hun.

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

Mae'r enghreifftiau ar y dudalen hon yn defnyddio /v1/chat/completions. Mae'r un ddolen yn rhedeg ar /v1/responses a /v1/messages; lle mae fformat yn sillafu rhywbeth yn wahanol, mae'r adrannau isod yn dangos y tri.

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)

Nid yw'r ateb cyntaf yn ateb y cwestiwn. Mae'n gofyn am alwad:

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

Ar ôl i chi anfon y canlyniad, mae'r ateb nesaf yn ateb cyffredin: mae message.content yn dal y testun ac mae finish_reason yn stop.

Y ddolen, cam wrth gam

Cam Pwy Beth sy'n digwydd
1 Chi Anfonwch messages ynghyd â tools, rhestr y ffwythiannau y caiff y model ofyn amdanynt.
2 Model Mae'r ateb yn cario tool_calls a finish_reason: "tool_calls". Mae pob galwad yn enwi ffwythiant ac yn rhoi ei ddadleuon.
3 Chi Dadansoddwch arguments pob galwad a rhedwch eich ffwythiant.
4 Chi Ychwanegwch neges yr assistant ac un neges tool am bob galwad at messages, yna anfonwch y cais eto gyda'r un tools.
5 Model Mae'r model yn ateb mewn testun gyda finish_reason: "stop", neu'n gofyn am fwy o alwadau. Yn yr achos hwnnw ewch yn ôl i gam 3.

Un tro model yw un cais. Nid yw'r API yn cadw sgwrs rhwng ceisiadau ac nid yw'n gosod nifer o rowndiau: mae eich cod yn dal messages ac yn penderfynu pryd i stopio.

Diffinio offer

Arae yw tools gydag un cofnod am bob ffwythiant. Mae pob model yn y catalog yn ei dderbyn; mae GET /v1/models yn adrodd capabilities.tools: true am bob id.

Maes Math Disgrifiad
type string Bob amser yn function.
function.name string Yr enw y mae'r model yn ei ddefnyddio pan fydd yn gofyn am y ffwythiant hwn. Gofynnol.
function.description string Beth mae'r ffwythiant yn ei wneud, mewn iaith blaen.
function.parameters object Y dadleuon fel sgema JSON gyda type: "object" ar y brig. Gweler Allweddeiriau sgema isod.

Mae gan bob pwynt terfyn ei sillafiad ei hun o offeryn. Anfonwch yr un sy'n perthyn i'r pwynt terfyn rydych yn ei alw:

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

Mae tool_choice yn dweud a gaiff y model, neu a rhaid iddo, alw offeryn. Fe'i darllenir gyda tools yn unig.

Gwerth Disgrifiad Yn cael ei gymhwyso gan
"auto" Mae'r model yn penderfynu a yw'n ateb mewn testun neu'n galw offeryn. Dyma'r rhagosodiad. Pob model
"required" Mae'r ateb yn galw o leiaf un offeryn. Modelau pwysau agored a gynhelir
{"type": "function", "function": {"name": "get_weather"}} Mae'r ateb yn galw'r ffwythiant hwn. Rhaid i'r enw fod yn un o'r ffwythiannau yn tools. Gadewir galwadau i ffwythiannau eraill allan o'r ateb. Modelau pwysau agored a gynhelir

Mae'r modelau Shannon (shannon-*) yn penderfynu ym mhob cais, fel gydag auto.

Gyda required neu ffwythiant a enwir, darllenwch finish_reason cyn i chi ddarllen tool_calls. Pan nad yw'r model yn cynhyrchu galwad, mae'r ateb yn ateb testun gyda finish_reason: "stop".

Ystyr /v1/chat/completions /v1/responses /v1/messages
Mae'r model yn penderfynu "auto" "auto" {"type": "auto"}
Galw o leiaf un offeryn "required" "required" {"type": "any"}
Galw un ffwythiant a enwir {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Derbynnir er mwyn cydnawsedd: tool_choice: "none" a parallel_tool_calls. Ar gyfer tro heb alwadau offer, anfonwch y cais heb tools.

Galwadau offer yn yr ateb

Maes Math Disgrifiad
finish_reason string tool_calls pan fo'r ateb yn cario o leiaf un alwad.
message.tool_calls array Un cofnod am bob galwad. Mae'r maes yn bresennol dim ond pan ofynnodd y model am alwad.
tool_calls[].id string call_ ac yna 32 nod hecsadegol. Anfonwch ef yn ôl fel tool_call_id gyda'r canlyniad.
tool_calls[].type string Bob amser yn function.
tool_calls[].function.name string Y ffwythiant i'w redeg.
tool_calls[].function.arguments string Y dadleuon fel llinyn JSON, "{}" pan nad oes dim. Dadansoddwch ef cyn ei ddefnyddio.
message.content string | null null pan fo'r ateb yn cynnwys galwadau yn unig. Gall y modelau pwysau agored a gynhelir ddychwelyd testun wrth ymyl y galwadau; mae'r modelau Shannon yn dychwelyd null.

Yr un alwad ym mhob fformat. Ar /v1/responses mae'n eitem function_call o output, gyda arguments fel llinyn JSON. Ar /v1/messages mae'n floc cynnwys tool_use y mae ei input yn wrthrych JSON, mae ei id yn dechrau gyda toolu_, ac mae stop_reason yn 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\"}"
        }
      }
    ]
  }
}

Sawl galwad mewn un tro

Gall ateb gario sawl galwad. Rhedwch bob un ohonynt ac anfonwch un canlyniad am bob galwad, pob un gyda'i tool_call_id ei hun, yn y cais nesaf.

Mae'r modelau pwysau agored a gynhelir yn dychwelyd pob galwad unigryw unwaith: mae dwy alwad gyda'r un enw a'r un dadleuon yn cyrraedd fel un.

Galwadau offer wedi'u ffrydio

Gyda stream: true, mae galwad yn cyrraedd mewn un darn: mae'r darn yn dal y llinyn arguments cyflawn, felly nid oes darnau i'w huno. Mae index yn cyfrif galwadau'r tro o 0.

data: un darn, wedi'i fformatio
{
  "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
    }
  ]
}
Pwynt terfyn Beth sy'n cyrraedd
/v1/chat/completions Un chat.completion.chunk am bob galwad, gyda'r alwad yn delta.tool_calls[0]. Mae gan y darn olaf finish_reason: "tool_calls" a usage.
/v1/responses Am bob galwad: response.output_item.added (eitem function_call gydag arguments gwag), response.function_call_arguments.delta (y llinyn cyfan), response.function_call_arguments.done, response.output_item.done.
/v1/messages Am bob galwad: content_block_start (bloc tool_use gydag input gwag), un content_block_delta y mae ei input_json_delta.partial_json yn holl destun y dadleuon, content_block_stop. Yna mae message_delta yn cario stop_reason: "tool_use".

Ar shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1, mae cais wedi'i ffrydio sy'n cario tools yn cyflwyno testun ei ateb mewn un delta content ar ddiwedd y tro. Ffrydio

Anfon canlyniadau yn ôl

Mae'r ail gais yn ailadrodd y sgwrs ac yn ychwanegu dau beth: tro'r assistant a ofynnodd am y galwadau, ac un canlyniad am bob galwad.

{
  "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\"}"
    }
  ]
}
  • Anfonwch dro'r assistant yn ôl fel y cawsoch ef, cyn y canlyniadau. Mae pob canlyniad yn cael ei baru â'i alwad gan yr id: tool_call_id ar /v1/chat/completions, call_id ar /v1/responses, tool_use_id ar /v1/messages.
  • Testun yw canlyniad. Cyfresolwch wrthrych yn llinyn JSON ar gyfer content (output ar /v1/responses). Ar /v1/messages mae content bloc tool_result yn llinyn neu'n rhestr o flociau testun.
  • Yn nhro'r assistant, mae function.arguments yn parhau'n llinyn JSON, yn union fel y cyrhaeddodd.
  • Gall y sgwrs ddod i ben â chanlyniad offeryn. Nid oes angen neges defnyddiwr newydd: mae'r model yn parhau o'r canlyniad.
  • Pan fo eich ffwythiant yn methu, anfonwch y methiant fel testun y canlyniad. Yna gall y model ei adrodd neu ofyn am alwad arall.

Allweddeiriau sgema

Sgema JSON yw parameters (input_schema ar /v1/messages). Mae teulu Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) a'r modelau pwysau agored a gynhelir yn ei dderbyn fel yr anfonwch ef.

Mae shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1 yn derbyn yr is-set hon, ar y tri phwynt terfyn:

Triniaeth Allweddeiriau
Darllenir fel y'i hanfonwyd Pob allweddair nad yw'n cael ei enwi yn y rhesi isod, er enghraifft type, properties, required, items, enum, description, minimum, maximum, anyOf ac allOf, ar bob lefel o'r sgema.
format Darllenir ar gyfer y gwerthoedd int32, int64, float, double, byte, date, date-time ac enum.
oneOf Darllenir fel anyOf.
Dim yn rhan o'r sgema y mae'r modelau hyn yn ei dderbyn $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 ac exclusiveMaximum pan fônt yn rhifau; gwerthoedd eraill format.

Ymddygiad a therfynau

  • Nid yw'r API yn gosod uchafswm ar nifer yr offer nac uchafswm ar nifer y rowndiau.
  • Gall corff cais fod hyd at 32 MiB, a rhaid i'r sgwrs gyda'i chanlyniadau ffitio ffenestr cyd-destun y model.
  • Pan fo cais yn cario tools, mae shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite a shannon-2-pro yn defnyddio temperature rhagosodedig o 0.2. Anfonwch temperature i osod gwerth arall.
  • Mae pob rownd yn gais ar ei ben ei hun: mae'n tynnu o'ch balans ac yn cyfrif tuag at amddiffyniad rhag llifogydd fel unrhyw gais arall. Terfynau a balans

Gwallau

Ateb arferol gyda statws 200 yw galwad offeryn. Mae'r gwallau hyn yn ymwneud â'r cais ei hun:

Statws Math Neges Pryd
400 invalid_request_error unknown model: <id> Nid yw model yn id yn y rhestr gyhoeddedig.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Nid yw tools yn arae, neu mae gan faes arall y math JSON anghywir.
413 invalid_request_error Failed to buffer the request body: … Mae corff y cais yn fwy na 32 MiB. Mae'r gwall yn cario code: "request_too_large".

Y model sy'n ysgrifennu'r dadleuon. Gwiriwch hwy yn erbyn eich sgema cyn i chi redeg y ffwythiant, fel y byddech yn gwirio unrhyw fewnbwn o'r tu allan.

Mae gwallau dilysu, balans a gweinydd yr un fath ag ar gyfer pob cais. Rheoli gwallau