Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Arkitetturi multi-għodda fil-produzzjoni

Lezzjoni 20 / 20 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Arkitetturi multi-għodda fil-produzzjoni
  2. Arkitettura saffata
  3. Orkestratur tal-produzzjoni
  4. Konfigurazzjoni dikjarattiva
  5. Osservabbiltà u monitoraġġ
  6. Ġestjoni tal-ispejjeż
  7. Mudell: router intelliġenti
  8. Lista ta’ kontroll tal-produzzjoni
  9. Punti Ewlenin
  10. Ittestja l-għarfien tiegħek

Aġġornat fit-2 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI: l-għodda Code Interpreter issa teħtieġ parametru container (miżjud mal-eżempji kollha), il-partijiet tal-input tat-test huma ttajpjati bħala input_text, u t-tiftix fuq il-web juża l-għodda web_search (web_search_preview issa hija għodda antika mingħajr filtri tad-dominju). Il-fajls iġġenerati jiġu rkuprati bl-użu tal-funzjonijiet fichiers_generes u telecharger mil-Lezzjoni 10. Sorsi: Code Interpreter · Web search.

Arkitetturi multi-għodda fil-produzzjoni

Prototip multi-għodda jaħdem għax persuna waħda tużah, jaf il-limiti tiegħu, u jerġa’ jibda meta jfalli. Il-produzzjoni tneħħi t-tliet kundizzjonijiet f’daqqa. Dak li jsir kritiku mhux il-kwalità tat-tweġiba—dik diġà kienet hemm—imma tliet proprjetajiet li l-prototip ma kellux: li tkun taf x’ġara meta sejħa tfalli, li tipprevjeni loop li jitbiegħed milli jnixxi l-baġit tiegħek, u li tkun tista’ timmodifika l-imġiba mingħajr ma terġa’ tiddispjega.

Il-mudelli hawn taħt jindirizzaw kull wieħed minn dawn ir-rekwiżiti. M’għandekx tadottahom kollha f’daqqa: ibda bl-osservabbiltà, għax mingħajrha lanqas biss tkun taf liema mill-oħrajn qed jonqsuk.

Arkitettura saffata

Is-separazzjoni tar-responsabbiltajiet f’saffi mhix eleganza arkitettonika: tagħmel kull parti sostitwibbli. Il-benefiċċju konkret huwa li tista’ tbiddel l-orkestrazzjoni mingħajr ma tmiss l-interfaċċa, jew iżżid għodda mingħajr ma tikteb mill-ġdid il-loġika tan-negozju. L-erba’ saffi hawn taħt huma l-qsim minimu li jiflaħ fil-prattika.

# Saff 1: Interfaċċa - riċeviment tat-talba
# Saff 2: Orkestrazzjoni - ġestjoni tal-loop u r-routing
# Saff 3: Eżekuzzjoni - sejħiet tal-għodod u tal-funzjonijiet
# Saff 4: Osservabbiltà - logs, metriċi, traċċi

from openai import OpenAI
from dataclasses import dataclass, field
from datetime import datetime
import json
import time
import logging

logger = logging.getLogger("multi-outils")

@dataclass
class TraceExecution:
    """Traċċa tal-eżekuzzjoni għall-monitoraġġ."""
    requete_id: str
    debut: float = field(default_factory=time.time)
    tours: list = field(default_factory=list)
    outils_utilises: list = field(default_factory=list)
    tokens_total: int = 0
    erreurs: list = field(default_factory=list)
    duree_totale: float = 0.0

Orkestratur tal-produzzjoni

class OrchestreurProduction:
    def __init__(self, config: dict):
        self.client = OpenAI()
        self.config = config
        self.tools = self._construire_tools(config)
        self.dispatcher = self._construire_dispatcher(config)

    def _construire_tools(self, config: dict) -> list:
        """Jibni l-array tal-għodod mill-konfigurazzjoni."""
        tools = []

        if config.get("file_search"):
            tools.append({
                "type": "file_search",
                "vector_store_ids": config["file_search"]["vector_stores"],
                "max_num_results": config["file_search"].get("max_results", 10)
            })

        if config.get("web_search"):
            tools.append({
                "type": "web_search",
                "search_context_size": config["web_search"].get("context_size", "medium")
            })

        if config.get("code_interpreter"):
            tools.append({"type": "code_interpreter", "container": {"type": "auto"}})

        for func in config.get("fonctions", []):
            tools.append(func)

        return tools

    def _construire_dispatcher(self, config: dict) -> dict:
        """Jimmapja l-ismijiet tal-funzjonijiet mal-implementazzjonijiet tagħhom."""
        return config.get("implementations", {})

    def executer(self, requete: str, fichiers: list = None,
                 max_tours: int = 10) -> dict:
        """Jesegwixxi talba b'traċċar sħiħ."""
        trace = TraceExecution(
            requete_id=f"req_{int(time.time()*1000)}"
        )

        content = [{"type": "input_text", "text": requete}]
        if fichiers:
            for fid in fichiers:
                content.append({"type": "input_file", "file_id": fid})

        messages = [{"role": "user", "content": content}]

        try:
            for tour in range(max_tours):
                debut_tour = time.time()

                response = self.client.responses.create(
                    model=self.config.get("model", "gpt-5.6-terra"),
                    input=messages,
                    tools=self.tools,
                    instructions=self.config.get("instructions", "")
                )

                trace.tokens_total += response.usage.total_tokens

                # Identifika s-sejħiet tal-funzjonijiet
                appels = [
                    item for item in response.output
                    if item.type == "function_call"
                ]

                # Irreġistra l-għodod użati
                for item in response.output:
                    if hasattr(item, "type"):
                        trace.outils_utilises.append(item.type)

                trace.tours.append({
                    "numero": tour + 1,
                    "appels_fonction": len(appels),
                    "duree": time.time() - debut_tour
                })

                if not appels:
                    trace.duree_totale = time.time() - trace.debut
                    return {
                        "reponse": response.output_text,
                        "trace": trace
                    }

                # Eżegwixxi funzjonijiet personalizzati
                resultats = self._executer_fonctions(appels, trace)
                messages = response.output + resultats

        except Exception as e:
            trace.erreurs.append(str(e))
            trace.duree_totale = time.time() - trace.debut
            logger.error(f"Erreur requête {trace.requete_id}: {e}")
            return {"reponse": None, "erreur": str(e), "trace": trace}

        trace.duree_totale = time.time() - trace.debut
        return {"reponse": "Limite de tours", "trace": trace}

    def _executer_fonctions(self, appels: list, trace: TraceExecution) -> list:
        """Jesegwixxi funzjonijiet b'ġestjoni tal-iżbalji."""
        resultats = []
        for appel in appels:
            try:
                func = self.dispatcher.get(appel.name)
                if not func:
                    raise ValueError(f"Fonction inconnue : {appel.name}")

                args = json.loads(appel.arguments)
                resultat = func(**args)
                resultats.append({
                    "type": "function_call_output",
                    "call_id": appel.call_id,
                    "output": json.dumps(resultat)
                })
            except Exception as e:
                trace.erreurs.append(f"{appel.name}: {str(e)}")
                resultats.append({
                    "type": "function_call_output",
                    "call_id": appel.call_id,
                    "output": json.dumps({"error": str(e)})
                })
        return resultats

Konfigurazzjoni dikjarattiva

Li tmexxi d-definizzjonijiet tas-sistema barra mill-kodiċi u ġġibhom fil-konfigurazzjoni tbiddel min jista’ jintervjeni. Li taġġusta prompt tas-sistema, tneħħi għodda, jew timmodifika limitu tal-ispiża jsir bidla ta’ fajl—li tista’ tiġi riveduta u mħassra—minflok dispjegament. Fuq sistema li tevolvi kull ġimgħa, dik hija d-differenza bejn li titerazzjona u li tirreaġixxi.

config_assistant_commercial = {
    "model": "gpt-5.6-terra",
    "instructions": (
        "You are a sales assistant. You have access to CRM data, "
        "product documentation, the web, and data analysis. "
        "Prioritize internal data, enrich with web data."
    ),
    "file_search": {
        "vector_stores": ["vs_fiches_produit", "vs_propositions"],
        "max_results": 10
    },
    "web_search": {
        "context_size": "medium"
    },
    "code_interpreter": True,
    "fonctions": [
        {
            "type": "function",
            "name": "creer_opportunite",
            "description": "Create an opportunity in the CRM",
            "parameters": {
                "type": "object",
                "properties": {
                    "client": {"type": "string"},
                    "montant": {"type": "number"},
                    "probabilite": {"type": "integer"}
                },
                "required": ["client", "montant", "probabilite"],
                "additionalProperties": False
            },
            "strict": True
        }
    ],
    "implementations": {
        "creer_opportunite": lambda client, montant, probabilite:
            crm_service.creer_opportunite(client, montant, probabilite)
    }
}

orchestreur = OrchestreurProduction(config_assistant_commercial)
resultat = orchestreur.executer("Prepare a proposal for Acme Corp")

Osservabbiltà u monitoraġġ

Dashboard tal-metriċi

Tliet metriċi huma biżżejjed biex tibda, u kull waħda tweġib mistoqsija differenti: il-latency għal kull għodda tgħidlek liema qed tgħodd is-sistema, ir-rata ta’ falliment għal kull għodda tgħidlek liema hija fraġli, u l-ispiża għal kull talba tgħidlek liema qed titbiegħed. Medja globali fuq it-tlieta ma tweġib l-ebda waħda minn dawn il-mistoqsijiet.

class MetriquesMultiOutils:
    def __init__(self):
        self.requetes = []

    def enregistrer(self, trace: TraceExecution):
        self.requetes.append({
            "id": trace.requete_id,
            "timestamp": datetime.now().isoformat(),
            "duree": trace.duree_totale,
            "tours": len(trace.tours),
            "tokens": trace.tokens_total,
            "outils": list(set(trace.outils_utilises)),
            "erreurs": len(trace.erreurs),
            "cout_estime": self._estimer_cout(trace)
        })

    def _estimer_cout(self, trace: TraceExecution) -> float:
        """Jistma l-ispiża f'dollari tal-eżekuzzjoni."""
        # Rati approssimattivi għal gpt-5.6-terra: $2 / $12 kull miljun
        cout_input = trace.tokens_total * 0.6 * 0.000002
        cout_output = trace.tokens_total * 0.4 * 0.000012
        return round(cout_input + cout_output, 4)

    def rapport(self) -> dict:
        if not self.requetes:
            return {}
        durees = [r["duree"] for r in self.requetes]
        tokens = [r["tokens"] for r in self.requetes]
        couts = [r["cout_estime"] for r in self.requetes]

        return {
            "total_requetes": len(self.requetes),
            "duree_moyenne": sum(durees) / len(durees),
            "tokens_moyen": sum(tokens) / len(tokens),
            "cout_total": sum(couts),
            "taux_erreur": sum(1 for r in self.requetes if r["erreurs"] > 0) / len(self.requetes),
            "outils_les_plus_utilises": self._outils_frequents()
        }

    def _outils_frequents(self) -> dict:
        compteur = {}
        for r in self.requetes:
            for outil in r["outils"]:
                compteur[outil] = compteur.get(outil, 0) + 1
        return dict(sorted(compteur.items(), key=lambda x: -x[1]))

Ġestjoni tal-ispejjeż

class GestionnaireCouts:
    def __init__(self, budget_quotidien: float = 50.0):
        self.budget = budget_quotidien
        self.depenses_jour = 0.0
        self.date_reset = datetime.now().date()

    def peut_executer(self, cout_estime: float) -> bool:
        """Jiċċekkja jekk il-baġit jippermettix l-eżekuzzjoni."""
        aujourdhui = datetime.now().date()
        if aujourdhui > self.date_reset:
            self.depenses_jour = 0.0
            self.date_reset = aujourdhui

        return (self.depenses_jour + cout_estime) <= self.budget

    def enregistrer_depense(self, cout: float):
        self.depenses_jour += cout

    def budget_restant(self) -> float:
        return self.budget - self.depenses_jour

# Integrazzjoni fl-orkestratur
gestionnaire_couts = GestionnaireCouts(budget_quotidien=100.0)

def executer_avec_budget(orchestreur, requete, **kwargs):
    cout_estime = 0.05  # Stima konservattiva
    if not gestionnaire_couts.peut_executer(cout_estime):
        return {"erreur": "Daily budget reached", "restant": 0}

    resultat = orchestreur.executer(requete, **kwargs)
    cout_reel = resultat["trace"].tokens_total * 0.000002
    gestionnaire_couts.enregistrer_depense(cout_reel)

    return resultat

Mudell: router intelliġenti

Hekk kif il-każijiet ta’ użu jiżdiedu, it-tentazzjoni hija li tagħti kollox lil sistema waħda mgħammra b’kull għodda. Dik hija l-għażla l-aktar għalja: kull talba, anke dawk trivjali, iġġib magħha s-sett sħiħ ta’ definizzjonijiet tal-għodod. Router li jikklassifika t-talba l-ewwel, imbagħad isejjaħ orkestratur speċjalizzat, iżomm il-kuntesti qosra u jagħmel kull fluss kejjel separatament.

class RouteurIntelligent:
    def __init__(self):
        self.client = OpenAI()
        self.orchestreurs = {}

    def enregistrer(self, domaine: str, orchestreur: OrchestreurProduction):
        self.orchestreurs[domaine] = orchestreur

    def router(self, requete: str) -> dict:
        """Jiddetermina d-dominju u jirrotta lejn l-orkestratur korrett."""
        # Klassifikazzjoni mgħaġġla b'mudell ħafif
        response = self.client.responses.create(
            model="gpt-5.6-terra",
            input=f"Classify this request into a domain: {requete}\n"
                  f"Available domains: {list(self.orchestreurs.keys())}\n"
                  f"Respond only with the domain name.",
        )

        domaine = response.output_text.strip().lower()

        if domaine not in self.orchestreurs:
            domaine = "general"  # Fallback

        logger.info(f"Requête routee vers : {domaine}")
        return self.orchestreurs[domaine].executer(requete)

# Konfigurazzjoni
routeur = RouteurIntelligent()
routeur.enregistrer("commercial", OrchestreurProduction(config_assistant_commercial))
routeur.enregistrer("support", OrchestreurProduction(config_support))
routeur.enregistrer("rh", OrchestreurProduction(config_rh))

# Użu
resultat = routeur.router("How many vacation days do I have left?")
# -> Jirrotta awtomatikament lejn l-orkestratur tar-RH

Lista ta’ kontroll tal-produzzjoni

Din il-lista ta’ kontroll hija intenzjonalment qasira. Ma timmirax għall-eżawrjenza iżda tkopri l-punti li n-nuqqas tagħhom jiswielek f’inċidenti minflok skumdità—u li ma tistax iżżid f’ħin qasir il-jum li s-sistema diġà tkun f’idejn l-utenti.

checklist = {
    "securite": [
        "Validate arguments for each function",
        "Rate limiting per user",
        "Sanitize inputs and outputs",
        "No sensitive data in logs"
    ],
    "fiabilite": [
        "Retry with backoff on transient errors",
        "Circuit breaker per external service",
        "Timeout per tool and per global request",
        "Fallback when a tool is unavailable"
    ],
    "performance": [
        "Parallel execution of independent calls",
        "Cache frequent search results",
        "Limit the number of loop iterations",
        "Choose the model adapted to complexity (gpt-5.6-terra vs gpt-5.6-terra)"
    ],
    "observabilite": [
        "Structured logging for each call",
        "Latency and cost metrics",
        "Alerts on error rate",
        "Complete trace of each request"
    ],
    "couts": [
        "Daily budget with circuit breaker",
        "Cost estimation before execution",
        "Weekly spending report",
        "Model choice optimization by complexity"
    ]
}

Punti Ewlenin

  • Iddikomponi f’saffi: interfaċċa, orkestrazzjoni, eżekuzzjoni, osservabbiltà
  • Uża konfigurazzjoni dikjarattiva biex tiddefinixxi s-sistemi
  • Ittraċċa kull eżekuzzjoni għall-monitoraġġ u d-debugging
  • Implimenta maniġer tal-ispejjeż b’baġit kuljum
  • Router intelliġenti jqassam it-talbiet lill-orkestraturi t-tajbin

Ittestja l-għarfien tiegħek

Sejħa tal-funzjonijiet, tiftix, eżekuzzjoni: l-arsenal sħiħ f’ħames mistoqsijiet.

1. X'għandu jkun fih skema tajba ta' funzjoni?

Tweġiba: Tipi stretti u deskrizzjonijiet operattivi għal kull parametru—dan huwa l-kuntratt li l-mudell juża biex jiddeċiedi meta jsejjaħ u kif jimla; il-validazzjoni tiċħad il-bqija.

2. Web Search jew File Search: kif tagħżel?

Tweġiba: Web Search għal informazzjoni pubblika u riċenti; File Search għad-dokumenti indiċċjati tiegħek (chunking + ranking integrat)—u t-tiftix ibridu jgħaqqad it-tnejn meta t-tweġiba tkun fiż-żewġ dinjiet.

3. X'jippermetti Code Interpreter fl-API?

Tweġiba: Jesegwixxi kodiċi f’sandbox: jipproċessa CSV/Excel/immaġnijiet, jikkalkula b’mod preċiż, jipproduċi grafiċi—il-mudell jirraġuna, il-kodiċi jikkalkula, is-sandbox tiżola.

4. Għal xiex isservi Tool Search?

Tweġiba: Biex tesponi b’mod dinamiku katalogu kbir ta’ għodod: il-mudell ifittex l-għodda rilevanti minflok ma jirċievi mijiet ta’ skemi f’daqqa—il-kuntest jibqa’ ħafif, il-kapaċitajiet jibqgħu vasti.

5. Liema regoli japplikaw għal arkitettura multi-għodda fil-produzzjoni?

Tweġiba: Għodod b’ambitu ċar, ġestjoni tal-iżbalji u fallbacks għal kull għodda, sejħiet paralleli meta jkunu indipendenti, u osservabbiltà għal kull sejħa—ir-robustezza tiġi ddisinjata għodda b’għodda.

Kull għodda għandha t-territorju tagħha; il-produzzjoni tgħaqqadhom—l-arkitettura finali hawn fuq hija l-pjan ta’ referenza tiegħek.