Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Glaoigh ar an API le Uirlisí

Ceacht 5 as 14 Nuashonraithe 2 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Seol Uirlisí chuig API Mistral
  2. An Chéad Iarratas
  3. An Freagra ón tSamhail a Thuiscint
  4. An Freagra a Pharsáil agus tool_calls a Eastósct
  5. Nuair a Iarrann an tSamhail Faisnéis atá in Easnamh
  6. An Teachtaireacht Córais a Láimhseáil
  7. Cód Iomlán do Chéimeanna 2–3
  8. Príomhphointí

Seol Uirlisí chuig API Mistral

Tá do fheidhmeanna agus a sonruithe JSON sainmhínithe agat cheana. Anois, ní mór duit iad a sheoladh chuig API Mistral agus, níos tábhachtaí fós, tuiscint a fháil ar an méid a thugann an tsamhail ar ais. Táimid ag céimeanna 2 agus 3 den phróiseas anois: faigheann an tsamhail an t-iarratas ón úsáideoir in éineacht leis na huirlisí, agus cruthaíonn sí glao feidhme – nó diúltaíonn sí glao a dhéanamh, rud atá chomh húsáideach céanna.

An Chéad Iarratas

import os
import json
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Tools defined in the previous lesson
tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

# User message
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# API call with tools
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

An Freagra ón tSamhail a Thuiscint

Tá oibiacht message sa fhreagra a fhéadann dhá fhoirm a ghlacadh, agus caithfidh do chód déileáil leis an dá cheann ón gcéad lá. Sa chéad chás, freagraíonn an tsamhail go díreach toisc nach bhfuil aon fheidhm ag teastáil: tá téacs sa réimse content, agus tá tool_calls cothrom le None.

# response.choices[0].message.content contains the text response
# response.choices[0].message.tool_calls is None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

Sa dara cás, ba mhaith leis an tsamhail feidhm a ghlaowh. Tá an scéal bun os cionn anois: tá content folamh nó null, agus iompraíonn tool_calls an t-ualach.

# response.choices[0].message.content is None or empty
# response.choices[0].message.tool_calls contains the calls
message = response.choices[0].message

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"Function: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")
        print(f"ID: {tool_call.id}")

Aschur tipiciúil:

Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz

An Freagra a Pharsáil agus tool_calls a Eastósct

Seo an cód iomlán chun faisnéis a eastósct go glan ó ghlao uirlise:

message = response.choices[0].message

if message.tool_calls and len(message.tool_calls) > 0:
    tool_call = message.tool_calls[0]

    # Extract the function name
    function_name = tool_call.function.name

    # Parse JSON arguments into a Python dictionary
    function_params = json.loads(tool_call.function.arguments)

    # Retrieve the unique call identifier
    tool_call_id = tool_call.id

    print(f"The model wants to call: {function_name}")
    print(f"With parameters: {function_params}")
    print(f"Call ID: {tool_call_id}")
else:
    # The model responded directly
    print(f"Response: {message.content}")

Tagann trí phíosa faisnéise as an mbloc seo, agus is é an tríú ceann an ceann a dhéanann daoine dearmad air. Úsáidtear ainm na feidhme le haghaidh seoladh, úsáidtear na hargóintí parsáilte don ghlao, ach is é an tool_call_id an rud a ligeann don tsamhail do thoradh a nascadh leis an nglao ceart nuair a sheolann tú ar ais é. Caill é, agus beidh an casadh comhrá doshárú.

Nuair a Iarrann an tSamhail Faisnéis atá in Easnamh

Uaireanta, ní thugann an t-úsáideoir dóthain faisnéise. Tá bealach galánta ag an tsamhail as an scéal: ná glaowh ar fheidhm ar chor ar bith, agus cuir ceist shoiléirithe ina ionad.

messages = [
    {"role": "user", "content": "What is the status of my payment?"}
]

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

message = response.choices[0].message
print(message.content)
# → "I need the transaction ID to check the status.
#     Could you please provide the transaction number?"

Is é seo díreach an iompar atá uait. Tá a fhios ag an tsamhail go bhfuil transaction_id liostaithe in required; in ionad ID inchreidte a cheapadh agus iarratas a spreagadh ar shonraí nach bhfuil ann, tugann sí an urlár don úsáideoir. Is é seo freisin an léiriú is fearr ar úsáideacht an réimse required a pléadh sa cheacht roimhe seo.

An Teachtaireacht Córais a Láimhseáil

Ligeann an teachtaireacht chórais duit an t-iompar seo a chreatlach seachas bheith ag súil leis.

messages = [
    {
        "role": "system",
        "content": "You are a payment tracking assistant. "
                   "Respond in English. "
                   "Use the available tools to answer questions "
                   "about transactions. If the user does not provide "
                   "the transaction ID, ask for it politely."
    },
    {
        "role": "user",
        "content": "What is the status of payment T1001?"
    }
]

Léigh é líne ar líne: socraíonn an chéad abairt an ról, socraíonn an dara ceann tón agus teanga an chúntóra, sonraíonn an tríú ceann cathain ba chóir feidhmeanna a úsáid, agus tugann an ceann deireanach treoir shainráite do chás imeallach – faisnéis in easnamh. Seo iad na trí chás úsáide a moltar teachtaireacht chórais a úsáid ina leith, agus is leor iad formhór na huaire.

Cód Iomlán do Chéimeanna 2–3

Seo an cód iomlán, in-athúsáidte chun iarratas a sheoladh le huirlisí. Cuimsíonn sé gach rud thuas agus normalaíonn sé an freagra i bhfoclóir le dhá fhoirm, rud a shábhálann duit ó if message.tool_calls a scaipeadh ar fud d’iarratais.

import os
import json
from mistralai.client import Mistral

def call_mistral_with_tools(
    messages: list,
    tools: list,
    model: str = "mistral-large-latest",
    tool_choice: str = "auto"
) -> dict:
    """Sends a request to Mistral with tools and returns the parsed response."""
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    response = client.chat.complete(
        model=model,
        messages=messages,
        tools=tools,
        tool_choice=tool_choice
    )

    message = response.choices[0].message

    if message.tool_calls and len(message.tool_calls) > 0:
        return {
            "type": "tool_call",
            "message": message,
            "tool_calls": [
                {
                    "id": tc.id,
                    "function_name": tc.function.name,
                    "arguments": json.loads(tc.function.arguments)
                }
                for tc in message.tool_calls
            ]
        }

    return {
        "type": "text",
        "message": message,
        "content": message.content
    }

Tabhair faoi deara go ndéanann an tuiscint liosta athrá ar gach tool_calls, ní hamháin ar an gcéad cheann. Is féidir leis an tsamhail roinnt cinn a tháirgeadh ag an am céanna; déileálfar leis sin i gceacht ina dhiaidh sin, ach tá d’fheidhm áise réidh cheana féin chun déileáil leo.

Príomhphointí

  • Seol tools agus messages chuig client.chat.complete() chun glao feidhme a chumasú
  • Seiceáil i gcónaí an bhfuil message.tool_calls ann sula ndéanann tú iarracht parsáil a dhéanamh
  • Tá tool_call_id éigeantach chun an toradh a sheoladh ar ais chuig an tsamhail
  • Is teaghrán JSON iad na hargóintí ar cheart iad a pharsáil le json.loads()
  • D’fhéadfadh an tsamhail roghnú freagra a thabhairt go díreach mura bhfuil feidhm ag teastáil nó má tá faisnéis in easnamh