Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Κλήση του API με Εργαλεία

Μάθημα 5 / 14 Ενημερώθηκε 2 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Αποστολή Εργαλείων στο Mistral API
  2. Το Πρώτο Αίτημα
  3. Κατανόηση της Απόκρισης του Μοντέλου
  4. Ανάλυση της Απόκρισης και Εξαγωγή των tool_calls
  5. Όταν το Μοντέλο Ζητά Ελλείπουσες Πληροφορίες
  6. Διαχείριση του Μηνύματος Συστήματος
  7. Πλήρης Κώδικας για τα Βήματα 2–3
  8. Βασικά σημεία

Αποστολή Εργαλείων στο Mistral API

Έχετε ορίσει τις συναρτήσεις σας και τις προδιαγραφές JSON τους. Τώρα πρέπει να τις στείλετε στο Mistral API και, το σημαντικότερο, να κατανοήσετε τι επιστρέφει το μοντέλο. Βρισκόμαστε πλέον στα βήματα 2 και 3 της διαδικασίας: το μοντέλο λαμβάνει το αίτημα του χρήστη μαζί με τα εργαλεία και παράγει μια κλήση συνάρτησης — ή αρνείται να κάνει μία, κάτι που είναι εξίσου διδακτικό.

Το Πρώτο Αίτημα

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
)

Κατανόηση της Απόκρισης του Μοντέλου

Η απόκριση περιέχει ένα αντικείμενο message που μπορεί να λάβει δύο μορφές και ο κώδικάς σας πρέπει να τις διαχειρίζεται και τις δύο από την πρώτη ημέρα. Στην πρώτη περίπτωση, το μοντέλο απαντά απευθείας επειδή δεν απαιτείται συνάρτηση: το content περιέχει κείμενο και το tool_calls είναι 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?"

Στη δεύτερη περίπτωση, το μοντέλο επιθυμεί να καλέσει μια συνάρτηση. Η κατάσταση αντιστρέφεται: το content είναι κενό ή null, και το tool_calls μεταφέρει το ωφέλιμο φορτίο (payload).

# 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}")

Τυπική έξοδος:

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

Ανάλυση της Απόκρισης και Εξαγωγή των tool_calls

Ακολουθεί ο πλήρης κώδικας για την καθαρή εξαγωγή πληροφοριών από μια κλήση εργαλείου:

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

Τρία κομμάτια πληροφοριών προκύπτουν από αυτό το μπλοκ και το τρίτο είναι αυτό που οι άνθρωποι ξεχνούν. Το όνομα της συνάρτησης χρησιμοποιείται για τη δρομολόγηση, τα αναλυμένα ορίσματα χρησιμοποιούνται για την κλήση, αλλά το tool_call_id είναι αυτό που επιτρέπει στο μοντέλο να συσχετίσει το αποτέλεσμά σας με τη σωστή κλήση όταν το στέλνετε πίσω. Αν το χάσετε, ο γύρος της συνομιλίας καθίσταται μη ανακτήσιμος.

Όταν το Μοντέλο Ζητά Ελλείπουσες Πληροφορίες

Μερικές φορές ο χρήστης δεν παρέχει αρκετές πληροφορίες. Το μοντέλο διαθένει έναν κομψό τρόπο διαφυγής: να μην καλέσει καθόλου συνάρτηση και να κάνει αντίθετα μια διευκρινιστική ερώτηση.

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

Αυτή η συμπεριφορά είναι ακριβώς αυτό που θέλετε. Το μοντέλο γνωρίζει ότι το transaction_id αναφέρεται στα required· αντί να επινοήσει ένα πιθανό ID και να προκαλέσει αίτημα σε ανύπαρκτα δεδομένα, παραχωρεί τον λόγο στον χρήστη. Αυτή είναι επίσης η καλύτερη επίδειξη της χρησιμότητας του πεδίου required που καλύφθηκε στο προηγούμενο μάθημα.

Διαχείριση του Μηνύματος Συστήματος

Το μήνυμα συστήματος σας επιτρέπει να πλαισιώσετε αυτή τη συμπεριφορά αντί να ελπίζετε σε αυτήν.

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?"
    }
]

Διαβάστε το γραμμή προς γραμμή: η πρώτη πρόταση ορίζει τον ρόλο, η δεύτερη ορίζει τον τόνο και τη γλώσσα του βοηθού, η τρίτη καθορίζει πότε να χρησιμοποιούνται οι συναρτήσεις και η τελευταία δίνει μια ρητή οδηγία για μια οριακή περίπτωση — ελλείπουσες πληροφορίες. Αυτές είναι οι τρεις περιπτώσεις χρήσης για τις οποίες συνιστάται ένα μήνυμα συστήματος και τις περισσότερες φορές αρκούν.

Πλήρης Κώδικας για τα Βήματα 2–3

Ακολουθεί ο πλήρης, επαναχρησιμοποιήσιμος κώδικας για την αποστολή ενός αιτήματος με εργαλεία. Ενσωματώνει όλα τα παραπάνω και κανονικοποιεί την απόκριση σε ένα λεξικό με δύο μορφές, γλιτώνοντάς σας από τη διασπορά ελέγχων if message.tool_calls σε όλη την εφαρμογή σας.

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
    }

Σημειώστε ότι η κατανόηση λίστας (list comprehension) επαναλαμβάνεται πάνω σε όλα τα tool_calls, όχι μόνο στο πρώτο. Το μοντέλο μπορεί να παράγει πολλά ταυτόχρονα· ένα επόμενο μάθημα θα καλύψει αυτό το θέμα, αλλά η βοηθητική σας συνάρτηση είναι ήδη έτοιμη να τα διαχειριστεί.

Βασικά σημεία

  • Στείλτε tools και messages στο client.chat.complete() για να ενεργοποιήσετε την κλήση συναρτήσεων
  • Ελέγχετε πάντα αν υπάρχει το message.tool_calls πριν επιχειρήσετε την ανάλυση
  • Το tool_call_id είναι υποχρεωτικό για την αποστολή του αποτελέσματος πίσω στο μοντέλο
  • Τα ορίσματα είναι μια συμβολοσειρά JSON που πρέπει να αναλυθεί με το json.loads()
  • Το μοντέλο μπορεί να επιλέξει να απαντήσει απευθείας εάν δεν χρειάζεται συνάρτηση ή εάν λείπουν πληροφορίες