ai-agents-for-beginners

Δημιουργία Τοπικών Πρακτόρων Τεχνητής Νοημοσύνης Χρησιμοποιώντας το Microsoft Foundry Local και Qwen

Δημιουργία Τοπικών Πρακτόρων Τεχνητής Νοημοσύνης

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

Γιατί θα θέλατε αυτό; Τρεις λόγοι που ανακύπτουν συνεχώς στην πραγματική μηχανική εργασία:

Το ζήτημα είναι ότι ανταλλάσσετε ένα κορυφαίο μοντέλο σύννεφου με ένα Μικρό Μοντέλο Γλώσσας (SLM) που τρέχει στον CPU, GPU ή NPU σας. Αυτό το μάθημα αφορά την κατασκευή πρακτόρων που είναι καλοί μέσα σε αυτόν τον περιορισμό αντί να προσποιούνται ότι ο περιορισμός δεν υπάρχει.

Εισαγωγή

Αυτό το μάθημα θα καλύψει:

Στόχοι Μάθησης

Μετά την ολοκλήρωση αυτού του μαθήματος, θα ξέρετε πώς να:

Προαπαιτούμενα

Αυτό το μάθημα υποθέτει ότι έχετε ολοκληρώσει τα προηγούμενα μαθήματα και είστε άνετοι με:

Θα χρειαστείτε επίσης:

Μικρά Μοντέλα Γλώσσας: Το Κατάλληλο Εργαλείο για Τοπική Εργασία

Ένα κορυφαίο μοντέλο σύννεφου έχει εκατοντάδες δισεκατομμύρια παραμέτρους και ένα κέντρο δεδομένων πίσω του. Ένα SLM έχει μερικά δισεκατομμύρια παραμέτρους και πρέπει να χωράει στη μνήμη RAM του φορητού σας υπολογιστή. Αυτή η διαφορά θέτει σαφείς προσδοκίες.

Τα SLMs είναι καλά σε:

Τα SLMs είναι πιο αδύναμα σε:

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

flowchart LR
    U[Προγραμματιστής] --> A[Τοπικός αντιπρόσωπος SLM]
    A -->|αποφασίζει ποιο εργαλείο| T1[διάβασε_αρχείο]
    A -->|αποφασίζει ποιο εργαλείο| T2[αναζήτηση_έγγραφα RAG]
    A -->|αποφασίζει ποιο εργαλείο| T3[ανάλυση_κώδικα]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[Απάντηση, πλήρως στην συσκευή]

Microsoft Foundry Local

Το Microsoft Foundry Local είναι ένα ελαφρύ περιβάλλον εκτέλεσης που κατεβάζει, διαχειρίζεται και εξυπηρετεί μοντέλα εξ ολοκλήρου στη μηχανή σας. Το πιο σημαντικό χαρακτηριστικό για εμάς είναι ότι εκθέτει ένα OpenAI-συμβατό HTTP endpoint — που σημαίνει ότι το OpenAI SDK και ο OpenAI client του Microsoft Agent Framework λειτουργούν εναντίον του με μόνο αλλαγή στο base_url. Όλα όσα μάθατε για την κατασκευή πρακτόρων μεταφέρονται άμεσα· μόνο το endpoint μετακινείται από το σύννεφο στο localhost.

Το Foundry Local επιλέγει επίσης αυτόματα την καλύτερη έκδοση ενός μοντέλου για το υλικό σας — μια έκδοση για CPU, μία για CUDA/GPU ή μία για NPU — ώστε να μην χρειάζεται να βελτιστοποιείτε χειροκίνητα ανά μηχάνημα.

Ρύθμιση

Εγκαταστήστε το Foundry Local (δείτε την τεκμηρίωση για το λειτουργικό σας) και επιβεβαιώστε ότι λειτουργεί:

# Εγκατάσταση (π.χ. ακολουθήστε την τεκμηρίωση για την πλατφόρμα σας)
winget install Microsoft.FoundryLocal      # Windows
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Κατεβάστε και τρέξτε ένα μοντέλο Qwen, στη συνέχεια ξεκινήστε την τοπική υπηρεσία
foundry model run qwen2.5-7b-instruct
foundry service status

Μόλις η υπηρεσία τρέχει, έχετε ένα τοπικό, OpenAI-συμβατό endpoint (συνήθως http://localhost:PORT/v1). Το notebook χρησιμοποιεί το foundry-local-sdk για να ανακαλύπτει το endpoint αυτόματα, οπότε δεν χρειάζεται να κωδικοποιήσετε χειροκίνητα τη θύρα.

Κλήση Συνάρτησης Qwen: Γιατί Έχει Σημασία

Ένας πράκτορας είναι πράκτορας μόνο αν μπορεί να καλεί εργαλεία. Πολλά SLMs μπορούν να συνομιλούν, αλλά παράγουν αναξιόπιστες, στρεβλές κλήσεις εργαλείων. Τα μοντέλα Qwen έχουν εκπαιδευτεί για κλήση συναρτήσεων και παράγουν συνεπείς και καλά διαμορφωμένες δομές κλήσης εργαλείων — αυτό ακριβώς μετατρέπει το τοπικό μοντέλο συνομιλίας σε τοπικό πράκτορα.

Η ροή είναι ο τυπικός βρόχος κλήσης εργαλείων που ήδη γνωρίζετε, απλώς τρέχει στη συσκευή:

sequenceDiagram
    participant U as Χρήστης
    participant A as Πράκτορας Qwen (τοπικός)
    participant T as Τοπικό Εργαλείο
    U->>A: "Τι κάνει το auth.py;"
    A->>A: Απόφαση: κλήση read_file
    A->>T: read_file("auth.py")
    T-->>A: περιεχόμενο αρχείου
    A->>A: Σκέψη πάνω στο περιεχόμενο
    A-->>U: Εξήγηση

Τοπικό RAG

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

Χρησιμοποιούμε το Chroma, ένα ενσωματωμένο κατάστημα διανυσμάτων που τρέχει στη διαδικασία χωρίς διακομιστή για διαχείριση. Η ροή είναι πλήρως τοπική: τοπικό μοντέλο ενσωμάτωσης → τοπικά διανύσματα → τοπική ανάκτηση → τοπικό SLM.

flowchart TB
    D[Τα έγγραφά σας / κώδικας] --> E[Τοπικό μοντέλο ενσωμάτωσης]
    E --> V[(Chroma vector DB - στον δίσκο)]
    Q[Ερώτημα πράκτορα] --> QE[Τοπική ενσωμάτωση ερωτήματος]
    QE --> V
    V -->|κορυφαία-k κομμάτια| A[Πράκτορας Qwen]
    A --> Ans[Βασισμένη απάντηση]

Αυτό είναι το ίδιο μοτίβο Agentic RAG από το Μάθημα 5 — η μόνη αλλαγή είναι ότι κάθε στοιχείο τρέχει στη μηχανή σας.

Τοπικοί MCP Servers

Το MCP είναι μέσο μεταφοράς, όχι υπηρεσία νέφους. Ένας MCP server μπορεί να τρέξει ως τοπική διαδικασία στο stdio, εκθέτοντας εργαλεία στον πράκτορά σας μέσω του τυποποιημένου πρωτοκόλλου. Αυτό σας επιτρέπει να επαναχρησιμοποιήσετε το αυξανόμενο οικοσύστημα MCP servers — πρόσβαση στο σύστημα αρχείων, εντολές git, ερωτήματα βάσεων δεδομένων — εντελώς εκτός δικτύου.

Η στάση ασφάλειας διαφέρει από το σύννεφο, αλλά δεν απουσιάζει: ένας τοπικός MCP server τρέχει ακόμη με τα δικαιώματα του χρήστη σας, οπότε περιορίστε το τι μπορεί να αγγίξει (ένα φάκελο έργου, όχι ολόκληρο τον προσωπικό σας φάκελο) και θεωρείστε τις εξόδους του ως εισόδους για επικύρωση.

Υβριδικά Μοτίβα Νέφους και Τοπικού

Τοπικά πρώτα δεν σημαίνει μόνο τοπικά. Οι ώριμες λύσεις δρομολογούν ανάλογα με την ευαισθησία και τη δυσκολία:

Κατάσταση Πού τρέχει
Ευαίσθητος κώδικας / δεδομένα, ή εκτός δικτύου Τοπικό SLM
Απλή, οριοθετημένη εργασία Τοπικό SLM (φθηνό, γρήγορο)
Δύσκολος πολυβηματικός συλλογισμός σε μη ευαίσθητα δεδομένα Μοντέλο νέφους
Όλα, κατά τη διάρκεια διακοπής Τοπικό SLM (ομαλή υποβάθμιση)

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

flowchart LR
    Q[Αίτημα] --> S{Ευαίσθητο ή εκτός σύνδεσης;}
    S -->|ναι| L[Τοπικό SLM]
    S -->|όχι| C{Απαιτεί βαθύ συλλογισμό;}
    C -->|όχι| L
    C -->|ναι| Cloud[Μοντέλο cloud]
    L --> Out[Απόκριση]
    Cloud --> Out

Εργαστήριο: Ένας Τοπικός Βοηθός Μηχανικού

Ανοίξτε το code_samples/17-local-agent-foundry-local.ipynb και δουλέψτε πάνω σε αυτό. Θα κατασκευάσετε έναν τοπικό βοηθό μηχανικού που τρέχει εξ ολοκλήρου στον σταθμό εργασίας σας και μπορεί να:

  1. Καλεί εργαλεία — μέσω κλήσης συναρτήσεων Qwen μέσω Foundry Local.
  2. Εκτελεί τοπικές λειτουργίες αρχείων — καταλογίζει και διαβάζει αρχεία σε φάκελο έργου.
  3. Αναλύει κώδικα — δίνει βασικά μετρικά σε ένα αρχείο πηγής.
  4. Αναζητά τεκμηρίωση — τοπικό RAG σε φάκελο εγγράφων με χρήση Chroma.
  5. Χρησιμοποιεί MCP — συνδέεται σε τοπικό MCP server (απλοϊκή παράλειψη αν δεν υπάρχει ρυθμισμένος).

Δεν χρησιμοποιείται καμία συμπερασματική λειτουργία νέφους σε κανένα σημείο.

Οδηγός

Ο βοηθός συνδέεται στο Foundry Local μέσω του OpenAI-συμβατού endpoint, έτσι ο κώδικας του πράκτορα μοιάζει σχεδόν ίδιος με τα μαθήματα νέφους — μόνο ο client αλλάζει:

from foundry_local import FoundryLocalManager
from openai import OpenAI

# Το Foundry Local εντοπίζει/κατεβάζει το μοντέλο και μας παρέχει ένα τοπικό σημείο πρόσβασης.
manager = FoundryLocalManager(\"qwen2.5-7b-instruct\")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # Το api_key είναι ένας τοπικός προσωρινός δείκτης.

Τα εργαλεία είναι απλές συναρτήσεις Python με εύρος σε φάκελο έργου:

def read_file(path: str) -> str:
    \"\"\"Read a file, but only inside the sandboxed project directory.\"\"\"
    full = (PROJECT_ROOT / path).resolve()
    if PROJECT_ROOT not in full.parents and full != PROJECT_ROOT:
        return \"Access denied: path is outside the project directory.\"
    return full.read_text(encoding=\"utf-8\")

Σημειώστε τον έλεγχο sandbox — ακόμη και τοπικά, ένα εργαλείο που διαβάζει αυθαίρετα μονοπάτια είναι ρίσκο. Το notebook διατηρεί κάθε εργαλείο περιορισμένο σε ένα μόνο φάκελο έργου.

Έλεγχος Γνώσης

Ελέγξτε την κατανόησή σας πριν προχωρήσετε στην ανάθεση.

1. Δώστε δύο συγκεκριμένους λόγους για να τρέξετε έναν πράκτορα τοπικά αντί στο σύννεφο.

Απάντηση Κάποιοι από: **απόρρητο** (ο κώδικας και τα δεδομένα δεν φεύγουν ποτέ από το μηχάνημα), **κόστος** (δεν υπάρχει χρέωση ανά token για συμπεραστική λειτουργία), και **λειτουργία εκτός δικτύου** (λειτουργεί χωρίς δίκτυο — σε αεροπλάνο, σε ασφαλή χώρο ή κατά τη διάρκεια διακοπής). Οι κανονισμοί/περιορισμοί που απαγορεύουν την αποστολή δεδομένων εκτός συσκευής είναι συχνή αιτία για το απόρρητο.

2. Ποια είναι η προτεινόμενη κατανομή εργασίας μεταξύ ενός SLM και των εργαλείων του σε έναν τοπικό πράκτορα, και γιατί;

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

3. Τι κάνει δυνατή την επαναχρησιμοποίηση του κώδικα πρακτόρων νέφους με το Foundry Local;

Απάντηση Το Foundry Local εκθέτει ένα **OpenAI-συμβατό HTTP endpoint**. Το OpenAI SDK και ο OpenAI client του Agent Framework λειτουργούν εναντίον του αλλάζοντας μόνο το `base_url` (και χρησιμοποιώντας τοπικό κλειδί API placeholder). Όλα τα άλλα στον κώδικα πράκτορα μένουν ίδια.

4. Γιατί χρησιμοποιούμε συγκεκριμένα ένα μοντέλο κλήσης συναρτήσεων Qwen αντί για οποιοδήποτε SLM;

Απάντηση Επειδή ένας πράκτορας πρέπει να παράγει αξιόπιστες, καλά διαμορφωμένες **κλήσεις εργαλείων**. Πολλά SLMs μπορούν να συνομιλούν αλλά παράγουν στρεβλές ή ασυνεπείς δομές κλήσης εργαλείων. Τα μοντέλα Qwen εκπαιδεύονται για κλήση συναρτήσεων και παράγουν συνεπείς κλήσεις εργαλείων, που είναι αυτό που μετατρέπει ένα τοπικό μοντέλο συνομιλίας σε ένα λειτουργικό τοπικό πράκτορα.

5. Στη ροή τοπικού RAG, ποια από τα στοιχεία τρέχουν στο μηχάνημα;

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

6. Ένας τοπικός MCP server τρέχει στο μηχάνημά σας. Σημαίνει αυτό αυτόματα ότι είναι ασφαλής; Ποια προφύλαξη πρέπει να λάβετε;

Απάντηση Όχι. Ένας τοπικός MCP server τρέχει με τα δικαιώματα του χρήστη σας, επομένως μπορεί να αγγίξει οτιδήποτε μπορεί και εσείς. Περιορίστε το σε ό,τι χρειάζεται (π.χ. ένα φάκελο έργου και όχι ολόκληρο τον προσωπικό φάκελο) και θεωρείστε τις εξόδους του ως εισόδους για επικύρωση πριν ενεργήσετε πάνω τους.

7. Περιγράψτε έναν λογικό υβριδικό κανόνα δρομολόγησης που περιλαμβάνει ένα τοπικό μοντέλο.

Απάντηση Δρομολογήστε ευαίσθητα ή εκτός δικτύου αιτήματα στο τοπικό SLM· δρομολογήστε απλές οριοθετημένες εργασίες στο τοπικό SLM για ταχύτητα και κόστος· δρομολογήστε δύσκολο, πολυβηματικό συλλογισμό σε μη ευαίσθητα δεδομένα σε μοντέλο νέφους· και επιστρέψτε στο τοπικό SLM αν το σύννεφο δεν είναι διαθέσιμο, ώστε ο πράκτορας να υποβαθμιστεί ομαλά αντί να αποτύχει. Αυτή είναι η δρομολόγηση μοντέλου (Μάθημα 16) με το τοπικό μηχάνημα ως ένα από τα μοντέλα.

8. Ποιος είναι ένας ρεαλιστικός ελάχιστος αριθμός RAM για την εκτέλεση του τοπικού πράκτορα σε αυτό το μάθημα, και τι κερδίζετε με περισσότερη RAM;

Απάντηση Περίπου **8 GB** είναι ρεαλιστικό ελάχιστο· 16 GB+ είναι άνετο. Περισσότερη RAM σας επιτρέπει να τρέχετε μεγαλύτερα, πιο ικανά μοντέλα και να διατηρείτε περισσότερο πλαίσιο στη μνήμη. Μια GPU ή NPU επιταχύνει τη συμπερασματική διαδικασία αλλά δεν είναι υποχρεωτική — το Foundry Local επιλέγει έκδοση CPU αν δεν υπάρχει επιταχυντής διαθέσιμος.

Ανάθεση

Επεκτείνετε τον τοπικό βοηθό μηχανικού σε έναν τοπικό αναθεωρητή τεκμηρίωσης για ένα μικρό έργο της επιλογής σας (μπορείτε να χρησιμοποιήσετε έναν από τους φακέλους μαθημάτων αυτού του αποθετηρίου αν θέλετε).

Η υποβολή σας θα πρέπει:

  1. Να ευρετηριάσει έναν πραγματικό φάκελο εγγράφων/κώδικα στο Chroma (τουλάχιστον πέντε αρχεία).

  2. Να προσθέσει εργαλείο find_todos που σαρώνει το έργο για σχόλια TODO/FIXME και τα επιστρέφει με το αρχείο και τον αριθμό γραμμής — διατηρώντας τον ίδιο έλεγχο sandbox όπως το read_file.

  3. Κάντε τρεις ερωτήσεις στον πράκτορα που τον αναγκάζουν να συνδυάσει εργαλεία: μία καθαρή ερώτηση RAG, μία που απαιτεί ανάγνωση ενός συγκεκριμένου αρχείου και μία που απαιτεί εύρεση TODOs.
  4. Μετρήστε το: μετρήστε τον χρόνο για καθεμία από τις τρεις απαντήσεις και καταγράψτε τον σε ένα κελί markdown. Σχολιάστε αν η καθυστέρηση είναι αποδεκτή για την προτεινόμενη ροή εργασίας σας.

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

Περίληψη

Σε αυτό το μάθημα κατασκευάσατε έναν πράκτορα που τρέχει εξ ολοκλήρου στο δικό σας μηχάνημα:

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

Πρόσθετοι Πόροι

Προηγούμενο Μάθημα

Ανάπτυξη Κλιμακούμενων Πρακτόρων

Επόμενο Μάθημα

Ασφάλεια Πρακτόρων AI

Αποποίηση ευθυνών: Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη Co-op Translator. Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης.

This site is open source. Improve this page.