Léim go dtí an t-ábhar
Glaonna Feidhme

Glaonna Feidhme

Déan cur síos ar d'fheidhmeanna san iarratas agus freagraíonn an múnla leis na glaonna is mian leis a dhéanamh. Ritheann do chód iad agus seolann sé na torthaí ar ais: filleann an API glaonna uirlisí agus ní ritheann sé uirlis é féin.

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

Úsáideann na samplaí ar an leathanach seo /v1/chat/completions. Ritheann an lúb chéanna ar /v1/responses agus /v1/messages; nuair a litríonn formáid rud éigin ar bhealach difriúil, taispeánann na hailt thíos na trí cheann.

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)

Ní fhreagraíonn an chéad fhreagra an cheist. Iarrann sé glao:

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

Tar éis duit an toradh a sheoladh, is gnáthfhreagra é an chéad fhreagra eile: tá an téacs i message.content agus is é stop an finish_reason.

An lúb, céim ar chéim

Céim Cé Cad a tharlaíonn
1 Tusa Seol messages agus tools le chéile, liosta na bhfeidhmeanna a fhéadfaidh an múnla iarraidh.
2 Múnla Iompraíonn an freagra tool_calls agus finish_reason: "tool_calls". Ainmníonn gach glao feidhm agus tugann sé a hargóintí.
3 Tusa Parsáil arguments gach glao agus rith d'fheidhm.
4 Tusa Cuir an teachtaireacht chúntóra agus teachtaireacht tool amháin in aghaidh gach glao le messages, ansin seol an t-iarratas arís leis na tools chéanna.
5 Múnla Freagraíonn an múnla i dtéacs le finish_reason: "stop", nó iarrann sé tuilleadh glaonna. Sa chás sin téigh ar ais go céim 3.

Is casadh múnla amháin é iarratas amháin. Ní choinníonn an API aon chomhrá idir iarratais agus ní shocraíonn sé aon líon babhtaí: coinníonn do chód messages agus socraíonn sé cathain a stopfaidh sé.

Uirlisí a shainiú

Is eagar é tools le hiontráil amháin in aghaidh gach feidhme. Glacann gach múnla den chatalóg leis; tuairiscíonn GET /v1/models capabilities.tools: true do gach id.

Réimse Cineál Cur síos
type string function i gcónaí.
function.name string An t-ainm a úsáideann an múnla nuair a iarrann sé an fheidhm seo. Riachtanach.
function.description string Cad a dhéanann an fheidhm, i dteanga shimplí.
function.parameters object Na hargóintí mar JSON Schema le type: "object" ar bharr. Féach Eochairfhocail scéime thíos.

Tá litriú uirlise dá cuid féin ag gach críochphointe. Seol an ceann a bhaineann leis an gcríochphointe a ghlaonn tú:

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

Insíonn tool_choice an bhfuil cead ag an múnla uirlis a ghlaoch, nó an gcaithfidh sé. Ní léitear é ach le tools.

Luach Cur síos Curtha i bhfeidhm ag
"auto" Socraíonn an múnla an bhfreagróidh sé i dtéacs nó an nglaofaidh sé uirlis. Is é seo an réamhshocrú. Gach múnla
"required" Glaonn an freagra uirlis amháin ar a laghad. Múnlaí open-weight óstáilte
{"type": "function", "function": {"name": "get_weather"}} Glaonn an freagra an fheidhm seo. Caithfidh an t-ainm a bheith ar cheann de na feidhmeanna in tools. Fágtar glaonna ar fheidhmeanna eile as an bhfreagra. Múnlaí open-weight óstáilte

Socraíonn na múnlaí Shannon (shannon-*) i ngach iarratas, mar a dhéanann auto.

Le required nó feidhm ainmnithe, léigh finish_reason sula léann tú tool_calls. Nuair nach dtáirgeann an múnla aon ghlao, is freagra téacs é an freagra le finish_reason: "stop".

Brí /v1/chat/completions /v1/responses /v1/messages
Socraíonn an múnla "auto" "auto" {"type": "auto"}
Glaoigh uirlis amháin ar a laghad "required" "required" {"type": "any"}
Glaoigh feidhm ainmnithe amháin {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

Glactar leo ar mhaithe le comhoiriúnacht: tool_choice: "none" agus parallel_tool_calls. Le haghaidh casaidh gan glaonna uirlisí, seol an t-iarratas gan tools.

Glaonna uirlisí san fhreagra

Réimse Cineál Cur síos
finish_reason string tool_calls nuair a iompraíonn an freagra glao amháin ar a laghad.
message.tool_calls array Iontráil amháin in aghaidh gach glao. Tá an réimse ann amháin nuair a d'iarr an múnla glao.
tool_calls[].id string call_ agus 32 charachtar heicsidheachúlacha ina dhiaidh. Seol ar ais é mar tool_call_id leis an toradh.
tool_calls[].type string function i gcónaí.
tool_calls[].function.name string An fheidhm atá le rith.
tool_calls[].function.arguments string Na hargóintí mar shreang JSON, "{}" nuair nach bhfuil aon cheann ann. Parsáil é roimh úsáid.
message.content string | null null nuair nach bhfuil sa fhreagra ach glaonna. Is féidir leis na múnlaí open-weight óstáilte téacs a fhilleadh in aice leis na glaonna; filleann na múnlaí Shannon null.

An glao céanna i ngach formáid. Ar /v1/responses is mír function_call de output é, le arguments mar shreang JSON. Ar /v1/messages is bloc ábhair tool_use é a bhfuil réad JSON mar input air, tosaíonn a id le toolu_, agus is é 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\"}"
        }
      }
    ]
  }
}

Roinnt glaonna i gcasadh amháin

Is féidir le freagra roinnt glaonna a iompar. Rith gach ceann acu agus seol toradh amháin in aghaidh gach glao, gach ceann lena tool_call_id féin, san iarratas dár gcionn.

Filleann na múnlaí open-weight óstáilte gach glao ar leith uair amháin: tagann dhá ghlao leis an ainm céanna agus na hargóintí céanna mar cheann amháin.

Glaonna uirlisí sruthaithe

Le stream: true, tagann glao i bpíosa amháin: tá an tsreang arguments iomlán sa phíosa, mar sin níl aon blúirí le nascadh. Comhaireann index glaonna an chasaidh ó 0.

data: píosa amháin, formáidithe
{
  "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
    }
  ]
}
Críochphointe Cad a thagann
/v1/chat/completions chat.completion.chunk amháin in aghaidh gach glao, agus an glao i delta.tool_calls[0]. Tá finish_reason: "tool_calls" agus usage sa phíosa deireanach.
/v1/responses In aghaidh gach glao: response.output_item.added (mír function_call le arguments folamh), response.function_call_arguments.delta (an tsreang iomlán), response.function_call_arguments.done, response.output_item.done.
/v1/messages In aghaidh gach glao: content_block_start (bloc tool_use le input folamh), content_block_delta amháin a bhfuil input_json_delta.partial_json ann mar théacs iomlán na n-argóintí, content_block_stop. Ansin iompraíonn message_delta stop_reason: "tool_use".

Ar shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro agus shannon-coder-1, seachadann iarratas sruthaithe a iompraíonn tools téacs a fhreagra i delta content amháin ag deireadh an chasaidh. Sruthú

Torthaí a sheoladh ar ais

Athdhéanann an dara hiarratas an comhrá agus cuireann sé dhá rud leis: an casadh cúntóra a d'iarr na glaonna, agus toradh amháin in aghaidh gach glao.

{
  "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\"}"
    }
  ]
}
  • Seol an casadh cúntóra ar ais mar a fuair tú é, roimh na torthaí. Meaitseáiltear gach toradh lena ghlao de réir id: tool_call_id ar /v1/chat/completions, call_id ar /v1/responses, tool_use_id ar /v1/messages.
  • Is téacs é toradh. Sraithe réad go sreang JSON do content (output ar /v1/responses). Ar /v1/messages is sreang nó liosta bloc téacs é content bloc tool_result.
  • Sa chasadh cúntóra, fanann function.arguments mar shreang JSON, díreach mar a tháinig sé.
  • Is féidir leis an gcomhrá deireadh le toradh uirlise. Ní theastaíonn teachtaireacht úsáideora nua: leanann an múnla ón toradh.
  • Nuair a theipeann ar d'fheidhm, seol an teip mar théacs an toraidh. Ansin is féidir leis an múnla í a thuairisciú nó glao eile a iarraidh.

Eochairfhocail scéime

Is JSON Schema é parameters (input_schema ar /v1/messages). Faigheann teaghlach Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) agus na múnlaí open-weight óstáilte é mar a sheolann tú é.

Faigheann shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro agus shannon-coder-1 an fholimistir seo, ar na trí chríochphointe:

Cóireáil Eochairfhocail
Léite mar a seoladh Gach eochairfhocal nach ainmnítear sna sraitheanna thíos, mar shampla type, properties, required, items, enum, description, minimum, maximum, anyOf agus allOf, ar gach leibhéal den scéim.
format Léitear do na luachanna int32, int64, float, double, byte, date, date-time agus enum.
oneOf Léitear mar anyOf.
Nach cuid den scéim a fhaigheann na múnlaí 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 is uimhreacha iad; luachanna eile de format.

Iompar agus teorainneacha

  • Ní shocraíonn an API uasmhéid uirlisí ná uasmhéid babhtaí.
  • Is féidir le corp iarratais a bheith suas le 32 MiB, agus caithfidh an comhrá lena thorthaí a bheith ag luí le fuinneog comhthéacs an mhúnla.
  • Nuair a iompraíonn iarratas tools, úsáideann shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite agus shannon-2-pro temperature réamhshocraithe de 0.2. Seol temperature chun luach eile a shocrú.
  • Is iarratas ar leith é gach babhta: tarraingíonn sé as d'iarmhéid agus comhairtear i leith chosaint tuile é cosúil le haon iarratas eile. Teorainneacha agus iarmhéid

Earráidí

Is gnáthfhreagra le stádas 200 é glao uirlise. Baineann na hearráidí seo leis an iarratas féin:

Stádas Cineál Teachtaireacht Cathain
400 invalid_request_error unknown model: <id> Ní id den liosta foilsithe é model.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Ní eagar é tools, nó tá cineál JSON mícheart ar réimse eile.
413 invalid_request_error Failed to buffer the request body: … Tá corp an iarratais níos mó ná 32 MiB. Tá code: "request_too_large" san earráid.

Scríobhann an múnla na hargóintí. Seiceáil iad i gcoinne do scéime sula ritheann tú an fheidhm, mar a sheicfeá aon ionchur ón taobh amuigh.

Tá earráidí fíordheimhnithe, iarmhéide agus freastalaí mar an gcéanna le gach iarratas. Láimhseáil Earráide