ናብ ትሕዝቶ ዝለል
ግብር ጥሪ

ግብር ጥሪ

Functions ናትካ ኣብ ጠለብ ግለጾም እቲ ሞዴል ድማ ክግበሩ ዝደሊ ጥሪታት ይመልስ። ኮድካ የስርሖም እሞ ውጽኢታት ተመሊስካ ይልእኾ፦ እቲ API tool ጥሪታት ይመልስ እምበር tool ባዕሉ ኣየስርሕን።

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

እቲ ኣብዚ ገጽ ዘሎ ኣብነታት /v1/chat/completions ይጥቀም። እቲ ተመሳሳሊ loop ኣብ /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 እዩ።

እቲ loop፣ ስጉምቲ ብስጉምቲ

ስጉምቲ መን እንታይ ይኸውን
1 ንስኻ messages ምስ tools ብሓባር ልኣኽ፣ እቲ ዝርዝር functions ሞዴል ክሓትት ዝኽእል።
2 ሞዴል እቲ ምላሽ tool_calls ከምኡውን finish_reason: "tool_calls" ይሓዝ። ነፍሲ ወከፍ ጥሪ function ይሰምዮ ከምኡውን arguments ናቱ ይህብ።
3 ንስኻ arguments ናይ ነፍሲ ወከፍ ጥሪ parse ግበር እሞ function ናትካ ኣስርሕ።
4 ንስኻ እቲ assistant መልእኽቲ ከምኡውን ሓደ tool መልእኽቲ ንነፍሲ ወከፍ ጥሪ ናብ messages ወስኽ፣ ደሓር ተመሳሳሊ tools ሒዝካ እቲ ጠለብ ደጊምካ ልኣኽ።
5 ሞዴል እቲ ሞዴል ብ finish_reason: "stop" ብጽሑፍ ይመልስ፣ ወይ ተወሳኺ ጥሪታት ይሓትት። ኣብዚ ኩነታት ናብ ስጉምቲ 3 ተመለስ።

ሓደ ጠለብ ሓደ ናይ ሞዴል turn እዩ። እቲ API ኣብ መንጎ ጠለባት ዘተ ኣየቐምጥን ከምኡውን ቁጽሪ ዙርታት ኣይውስንን፦ ኮድካ messages ይሕዝ ከምኡውን መዓስ ደው ከም ዝብል ይውስን።

Tools ምግላጽ

tools ንነፍሲ ወከፍ function ሓደ entry ዘለዎ array እዩ። ነፍሲ ወከፍ ሞዴል ናይ ካታሎግ ይቕበሎ፤ GET /v1/models ንነፍሲ ወከፍ id capabilities.tools: true ይሕብር።

Field ዓይነት መግለጺ
type string ኩሉ ግዜ function።
function.name string እቲ ሞዴል ነዚ function ክሓትት ከሎ ዝጥቀሞ ስም። ግዴታ።
function.description string እቲ function እንታይ ከም ዝገብር፣ ብቀሊል ቋንቋ።
function.parameters object እቶም arguments ከም JSON Schema ምስ type: "object" ኣብ ላዕሊ። ኣብ ታሕቲ Schema keywords ርአ።

ነፍሲ ወከፍ endpoint ናቱ ፍሉይ ኣጻሓሕፋ ናይ tool ኣለዎ። እቲ ንዝጽውዕዎ 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 እቲ ሞዴል tool ክጽውዕ ይኽእል ወይ ክጽውዕ ኣለዎ እንተ ኮይኑ ይብል። ምስ tools ጥራይ ይነበብ።

ዋጋ መግለጺ ዝተጠቐመሉ
"auto" እቲ ሞዴል ብጽሑፍ ክመልስ ወይ tool ክጽውዕ ይውስን። እዚ ነባሪ እዩ። ኩሎም ሞዴላት
"required" እቲ ምላሽ ብውሑዱ ሓደ tool ይጽውዕ። ዝተሃንደሱ open-weight ሞዴላት
{"type": "function", "function": {"name": "get_weather"}} እቲ ምላሽ ነዚ function ይጽውዖ። እቲ ስም ካብቶም ኣብ tools ዘለዉ functions ሓደ ክኸውን ኣለዎ። ጥሪታት ናብ ካልኦት functions ካብ ምላሽ ይወጽኡ። ዝተሃንደሱ open-weight ሞዴላት

ሞዴላት Shannon (shannon-*) ኣብ ነፍሲ ወከፍ ጠለብ ይውስኑ፣ ከም ምስ auto።

ምስ required ወይ ዝተሰምየ function፣ ቅድሚ tool_calls ምንባብካ finish_reason ኣንብብ። እቲ ሞዴል ጥሪ ምስ ዘይፈጥር፣ እቲ ምላሽ ብ finish_reason: "stop" ጽሑፍ መልሲ እዩ።

ትርጉም /v1/chat/completions /v1/responses /v1/messages
እቲ ሞዴል ይውስን "auto" "auto" {"type": "auto"}
ብውሑዱ ሓደ tool ጸውዕ "required" "required" {"type": "any"}
ሓደ ዝተሰምየ function ጸውዕ {"type": "function", "function": {"name": "get_weather"}} {"type": "function", "name": "get_weather"} {"type": "tool", "name": "get_weather"}

ንምስምማዕ ይቕበል፦ tool_choice: "none" ከምኡውን parallel_tool_calls። ንturn ብዘይ tool ጥሪታት፣ እቲ ጠለብ ብዘይ tools ልኣኽ።

Tool ጥሪታት ኣብ ምላሽ

Field ዓይነት መግለጺ
finish_reason string እቲ ምላሽ ብውሑዱ ሓደ ጥሪ ምስ ዝሓዝ tool_calls።
message.tool_calls array ሓደ entry ንነፍሲ ወከፍ ጥሪ። እቲ field እቲ ሞዴል ጥሪ ምስ ዝሓትት ጥራይ ይርከብ።
tool_calls[].id string call_ ተኸቲሉ 32 hexadecimal ፊደላት። ምስ ውጽኢት ከም tool_call_id ተመሊስካ ልኣኾ።
tool_calls[].type string ኩሉ ግዜ function።
tool_calls[].function.name string ክሰርሕ ዘለዎ function።
tool_calls[].function.arguments string እቶም arguments ከም JSON string፣ ዋላ ሓደ ምስ ዘየለ "{}"። ቅድሚ ምጥቃም parse ግበሮ።
message.content string | null እቲ ምላሽ ጥሪታት ጥራይ ምስ ዝሓዝ null። ዝተሃንደሱ open-weight ሞዴላት ጽሑፍ ኣብ ጥቓ ጥሪታት ክመልሱ ይኽእሉ፤ Shannon ሞዴላት null ይመልሱ።

እቲ ተመሳሳሊ ጥሪ ኣብ ነፍሲ ወከፍ ቅርጺ። ኣብ /v1/responses ሓደ function_call item ናይ output እዩ፣ ምስ arguments ከም JSON string። ኣብ /v1/messages tool_use content block እዩ እቲ input ድማ JSON object እዩ፣ 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\"}"
        }
      }
    ]
  }
}

ብዙሓት ጥሪታት ኣብ ሓደ turn

ሓደ ምላሽ ብዙሓት ጥሪታት ክሓዝ ይኽእል። ኩሎም ኣስርሖም እሞ ኣብ ዝቕጽል ጠለብ ንነፍሲ ወከፍ ጥሪ ሓደ ውጽኢት፣ ነፍሲ ወከፍ ምስ ናቱ tool_call_id፣ ልኣኽ።

ዝተሃንደሱ open-weight ሞዴላት ነፍሲ ወከፍ ፍሉይ ጥሪ ሓንሳእ ይመልሱ፦ ክልተ ጥሪታት ብተመሳሳሊ ስምን ተመሳሳሊ argumentsን ከም ሓደ ይመጹ።

Streamed tool ጥሪታት

ምስ stream: true፣ ሓደ ጥሪ ብሓደ ቁራጽ ይመጽእ፦ እቲ chunk ምሉእ arguments string ይሓዝ፣ ስለዚ ዝጽነበሩ ቁራጽታት የለዉን። index ጥሪታት ናይ turn ካብ 0 ይቝጽር።

data: ሓደ chunk፣ ዝተኸየደ 
{
  "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]። እቲ ዳሕረዋይ chunk finish_reason: "tool_calls" ከምኡውን usage ኣለዎ።
/v1/responses ንነፍሲ ወከፍ ጥሪ፦ response.output_item.added (function_call item ምስ ባዶ arguments)፣ response.function_call_arguments.delta (ምሉእ string)፣ response.function_call_arguments.done፣ response.output_item.done።
/v1/messages ንነፍሲ ወከፍ ጥሪ፦ content_block_start (tool_use block ምስ ባዶ input)፣ ሓደ content_block_delta እቲ input_json_delta.partial_json ምሉእ ጽሑፍ arguments ዝኾነ፣ 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 ዝሓዘ streamed ጠለብ ጽሑፍ መልሱ ኣብ መወዳእታ ናይ turn ኣብ ሓደ content delta የቕርብ። ስትሪም

ውጽኢታት ምምላስ

እቲ ካልኣይ ጠለብ ዘተ ይደግም ከምኡውን ክልተ የወስኽ፦ እቲ ጥሪታት ዝሓተተ assistant turn፣ ከምኡውን ሓደ ውጽኢት ንነፍሲ ወከፍ ጥሪ።

{
  "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 turn ከምቲ ዝተቐበልካዮ ቅድሚ ውጽኢታት ተመሊስካ ልኣኾ። ነፍሲ ወከፍ ውጽኢት ብ id ምስ ጥሪኡ ይሰማማዕ፦ tool_call_id ኣብ /v1/chat/completions፣ call_id ኣብ /v1/responses፣ tool_use_id ኣብ /v1/messages።
  • ውጽኢት ጽሑፍ እዩ። object ንሓደ JSON string ንምውሳድ ኣብ content (output ኣብ /v1/responses) serialise ግበሮ። ኣብ /v1/messages እቲ content ናይ tool_result block string ወይ ዝርዝር text blocks እዩ።
  • ኣብ assistant turn፣ function.arguments ከምቲ ዝመጸ JSON string ይተርፍ።
  • እቲ ዘተ ብ tool ውጽኢት ክውዳእ ይኽእል። ሓዲሽ user መልእኽቲ ኣየድልን፦ እቲ ሞዴል ካብ ውጽኢት ይቕጽል።
  • function ናትካ ምስ ዝወድቅ፣ እቲ ውድቀት ከም ጽሑፍ ውጽኢት ልኣኽ። እቲ ሞዴል ሽዑ ክሕብሮ ወይ ካልእ ጥሪ ክሓትት ይኽእል።

Schema keywords

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 ኣብ ኩሎም ሰለስተ endpoints እዚ ንኡስ ክፋል ይቕበሉ፦

ኣተሓሕዛ Keywords
ከምቲ ዝተላእከ ይነበብ ኣብ ታሕቲ ኣብ ዘለዉ ረድፍታት ዘይተሰምየ ነፍሲ ወከፍ keyword፣ ንኣብነት 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 ወሰን ቁጽሪ tools ወይ ወሰን ቁጽሪ ዙርታት የቐምጥን።
  • request body ክሳብ 32 MiB ክኸውን ይኽእል፣ ዘተ ምስ ውጽኢታቱ ድማ ኣብ context window ናይ ሞዴል ክሰፍሕ ኣለዎ።
  • ጠለብ tools ምስ ዝሓዝ፣ shannon-1.6-lite፣ shannon-1.6-pro፣ shannon-2-lite ከምኡውን shannon-2-pro ነባሪ temperature 0.2 ይጥቀሙ። ካልእ ዋጋ ንምዝውታር temperature ልኣኽ።
  • ነፍሲ ወከፍ ዙር ናይ ርእሱ ጠለብ እዩ፦ ካብ ሚዛንካ ይወስድ ከምኡውን ከም ዝኾነ ካልእ ጠለብ ኣብ flood protection ይቝጸር። ገደባትን ሚዛንን

ጌጋታት

tool ጥሪ ምስ ኩነታት 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 ኣይኮነን፣ ወይ ካልእ field ጌጋ JSON ዓይነት ኣለዎ።
413 invalid_request_error Failed to buffer the request body: … እቲ request body ካብ 32 MiB ይዓቢ። እቲ ጌጋ code: "request_too_large" ይሓዝ።

እቲ ሞዴል arguments ይጽሕፍ። ቅድሚ function ምስራሕካ፣ ከም ዝኾነ ወጻኢ ኣተዋዕዎ ትምርምሮ፣ ምስ schema ናትካ ርግጸኛ ኩን።

ምርግጋጽ፣ ሚዛን ከምኡውን server ጌጋታት ንነፍሲ ወከፍ ጠለብ ተመሳሳሊ እዮም። ሓጋይ ኣስተዳደር