Architektury wielonarzędziowe w środowisku produkcyjnym
Na tej stronie
Zaktualizowano 2 listopada 2026 na podstawie dokumentacji OpenAI: narzędzie Code Interpreter wymaga teraz parametru
container(dodano do wszystkich przykładów), części wejściowe tekstu są typowane jakoinput_text, a wyszukiwanie w sieci korzysta z narzędziaweb_search(web_search_previewjest obecnie narzędziem przestarzałym bez filtrów domenowych). Wygenerowane pliki pobiera się za pomocą funkcjifichiers_generesitelechargerz Lekcji 10. Źródła: Code Interpreter · Wyszukiwanie w sieci.
Architektury wielonarzędziowe w środowisku produkcyjnym
Prototyp wielonarzędziowy działa, ponieważ korzysta z niego jedna osoba, zna jego ograniczenia i restartuje go w razie awarii. Środowisko produkcyjne usuwa wszystkie trzy te warunki jednocześnie. Krytyczne nie jest już качество odpowiedzi – to było zapewnione wcześniej – lecz trzy właściwości, których prototypowi brakowało: wiedza o tym, co się stało, gdy wywołanie zawiedzie, zapobieganie pętli nieskończonej wypalającej budżet oraz możliwość modyfikacji zachowania bez ponownego wdrażania.
Poniższe wzorce odpowiadają każdemu z tych wymagań. Nie wdrażaj ich wszystkich naraz: zacznij od obserwowalności, bo bez niej nawet nie dowiesz się, którego z pozostałych elementów Ci brakuje.
Architektura warstwowa
Rozdzielenie odpowiedzialności na warstwy to nie kwestia elegancji architektonicznej – chodzi o to, by każda część była wymienna. Konkretna korzyść? Możesz zmienić orkiestrację, nie dotykając interfejsu, albo dodać narzędzie bez przepisywania logiki biznesowej. Poniższe cztery warstwy to minimalny podział, który sprawdza się w praktyce.
# Warstwa 1: Interfejs - odbieranie żądań
# Warstwa 2: Orkiestracja - zarządzanie pętlą i routing
# Warstwa 3: Wykonanie - wywołania narzędzi i funkcji
# Warstwa 4: Obserwowalność - logi, metryki, ślady
from openai import OpenAI
from dataclasses import dataclass, field
from datetime import datetime
import json
import time
import logging
logger = logging.getLogger("multi-narzedzia")
@dataclass
class SledzenieWykonania:
"""Ślad wykonania do monitorowania."""
identyfikator_zadania: str
start: float = field(default_factory=time.time)
cykle: list = field(default_factory=list)
uzyte_narzedzia: list = field(default_factory=list)
laczna_liczba_tokenow: int = 0
bledy: list = field(default_factory=list)
calkowity_czas_trwania: float = 0.0
Orkiestrator produkcyjny
class OrkiestratorProdukcji:
def __init__(self, konfiguracja: dict):
self.klient = OpenAI()
self.konfiguracja = konfiguracja
self.narzedzia = self._zbuduj_narzedzia(konfiguracja)
self.dispatcher = self._zbuduj_dispatcher(konfiguracja)
def _zbuduj_narzedzia(self, konfiguracja: dict) -> list:
"""Buduje tablicę narzędzi na podstawie konfiguracji."""
narzedzia = []
if konfiguracja.get("file_search"):
narzedzia.append({
"type": "file_search",
"vector_store_ids": konfiguracja["file_search"]["vector_stores"],
"max_num_results": konfiguracja["file_search"].get("max_results", 10)
})
if konfiguracja.get("web_search"):
narzedzia.append({
"type": "web_search",
"search_context_size": konfiguracja["web_search"].get("context_size", "medium")
})
if konfiguracja.get("code_interpreter"):
narzedzia.append({"type": "code_interpreter", "container": {"type": "auto"}})
for func in konfiguracja.get("funkcje", []):
narzedzia.append(func)
return narzedzia
def _zbuduj_dispatcher(self, konfiguracja: dict) -> dict:
"""Mapuje nazwy funkcji do ich implementacji."""
return konfiguracja.get("implementacje", {})
def wykonaj(self, zapytanie: str, pliki: list = None,
max_cykli: int = 10) -> dict:
"""Wykonuje żądanie z pełnym śledzeniem."""
slad = SledzenieWykonania(
identyfikator_zadania=f"req_{int(time.time()*1000)}"
)
tresc = [{"type": "input_text", "text": zapytanie}]
if pliki:
for fid in pliki:
tresc.append({"type": "input_file", "file_id": fid})
wiadomosci = [{"role": "user", "content": tresc}]
try:
for cykl in range(max_cykli):
start_cyklu = time.time()
odpowiedz = self.klient.responses.create(
model=self.konfiguracja.get("model", "gpt-5.6-terra"),
input=wiadomosci,
tools=self.narzedzia,
instructions=self.konfiguracja.get("instrukcje", "")
)
slad.laczna_liczba_tokenow += odpowiedz.usage.total_tokens
# Identyfikacja wywołań funkcji
wolania = [
element for element in odpowiedz.output
if element.type == "function_call"
]
# Rejestracja użytych narzędzi
for element in odpowiedz.output:
if hasattr(element, "type"):
slad.uzyte_narzedzia.append(element.type)
slad.cykle.append({
"numer": cykl + 1,
"liczba_wolan_funkcji": len(wolania),
"czas_trwania": time.time() - start_cyklu
})
if not wolania:
slad.calkowity_czas_trwania = time.time() - slad.start
return {
"odpowiedz": odpowiedz.output_text,
"slad": slad
}
# Wykonanie niestandardowych funkcji
wyniki = self._wykonaj_funkcje(wolania, slad)
wiadomosci = odpowiedz.output + wyniki
except Exception as e:
slad.bledy.append(str(e))
slad.calkowity_czas_trwania = time.time() - slad.start
logger.error(f"Błąd żądania {slad.identyfikator_zadania}: {e}")
return {"odpowiedz": None, "blad": str(e), "slad": slad}
slad.calkowity_czas_trwania = time.time() - slad.start
return {"odpowiedz": "Osiągnięto limit cykli", "slad": slad}
def _wykonaj_funkcje(self, wolania: list, slad: SledzenieWykonania) -> list:
"""Wykonuje funkcje z obsługą błędów."""
wyniki = []
for wolanie in wolania:
try:
func = self.dispatcher.get(wolanie.name)
if not func:
raise ValueError(f"Nieznana funkcja: {wolanie.name}")
args = json.loads(wolanie.arguments)
rezultat = func(**args)
wyniki.append({
"type": "function_call_output",
"call_id": wolanie.call_id,
"output": json.dumps(rezultat)
})
except Exception as e:
slad.bledy.append(f"{wolanie.name}: {str(e)}")
wyniki.append({
"type": "function_call_output",
"call_id": wolanie.call_id,
"output": json.dumps({"error": str(e)})
})
return wyniki
Konfiguracja deklaratywna
Wyniesienie definicji systemu poza kod i przeniesienie ich do konfiguracji zmienia to, kto może interweniować. Dostosowanie promptu systemowego, usunięcie narzędzia czy zmiana limitu kosztów staje się zmianą w pliku – podlegającą przeglądowi i odwracalną – zamiast wymagać wdrożenia. W systemie ewoluującym co tydzień to właśnie różnica między iterowaniem a reagowaniem.
konfiguracja_asystenta_sprzedazy = {
"model": "gpt-5.6-terra",
"instrukcje": (
"Jesteś asystentem sprzedaży. Masz dostęp do danych CRM, "
"dokumentacji produktów, sieci oraz analizy danych. "
"Nadawaj priorytet danym wewnętrznym, wzbogacaj je danymi z sieci."
),
"file_search": {
"vector_stores": ["vs_karty_produktow", "vs_oferty"],
"max_results": 10
},
"web_search": {
"context_size": "medium"
},
"code_interpreter": True,
"funkcje": [
{
"type": "function",
"name": "utworz_szanse_sprzedazowa",
"description": "Utwórz szansę sprzedażową w CRM",
"parameters": {
"type": "object",
"properties": {
"klient": {"type": "string"},
"kwota": {"type": "number"},
"prawdopodobienstwo": {"type": "integer"}
},
"required": ["klient", "kwota", "prawdopodobienstwo"],
"additionalProperties": False
},
"strict": True
}
],
"implementacje": {
"utworz_szanse_sprzedazowa": lambda klient, kwota, prawdopodobienstwo:
serwis_crm.utworz_szanse_sprzedazowa(klient, kwota, prawdopodobienstwo)
}
}
orkiestrator = OrkiestratorProdukcji(konfiguracja_asystenta_sprzedazy)
wynik = orkiestrator.wykonaj("Przygotuj ofertę dla firmy Acme Corp")
Obserwowalność i monitorowanie
Panel metryk
Na początek wystarczą trzy metryki, a każda odpowiada na inne pytanie: opóźnienie per narzędzie powie Ci, które spowalnia system, wskaźnik błędów per narzędzie wskaże, które jest kruche, a koszt per żądanie – które wymyka się spod kontroli. Średnia globalna dla wszystkich trzech nie odpowiada na żadne z tych pytań.
class MetrykiWielonarzedziowe:
def __init__(self):
self.zadania = []
def zarejestruj(self, slad: SledzenieWykonania):
self.zadania.append({
"id": slad.identyfikator_zadania,
"timestamp": datetime.now().isoformat(),
"czas_trwania": slad.calkowity_czas_trwania,
"liczba_cykli": len(slad.cykle),
"tokeny": slad.laczna_liczba_tokenow,
"narzedzia": list(set(slad.uzyte_narzedzia)),
"liczba_bledow": len(slad.bledy),
"szacowany_koszt": self._oszacuj_koszt(slad)
})
def _oszacuj_koszt(self, slad: SledzenieWykonania) -> float:
"""Szacuje koszt wykonania w dolarach."""
# Przybliżone stawki dla gpt-5.6-terra: 2 $ / 12 $ za milion
koszt_wejscia = slad.laczna_liczba_tokenow * 0.6 * 0.000002
koszt_wyjscia = slad.laczna_liczba_tokenow * 0.4 * 0.000012
return round(koszt_wejscia + koszt_wyjscia, 4)
def raport(self) -> dict:
if not self.zadania:
return {}
czasy = [r["czas_trwania"] for r in self.zadania]
tokeny = [r["tokeny"] for r in self.zadania]
koszty = [r["szacowany_koszt"] for r in self.zadania]
return {
"laczna_liczba_zadan": len(self.zadania),
"sredni_czas_trwania": sum(czasy) / len(czasy),
"srednia_liczba_tokenow": sum(tokeny) / len(tokeny),
"laczny_koszt": sum(koszty),
"wskaznik_bledow": sum(1 for r in self.zadania if r["liczba_bledow"] > 0) / len(self.zadania),
"najczesciej_uzywane_narzedzia": self._najczestsze_narzedzia()
}
def _najczestsze_narzedzia(self) -> dict:
licznik = {}
for r in self.zadania:
for narzedzie in r["narzedzia"]:
licznik[narzedzie] = licznik.get(narzedzie, 0) + 1
return dict(sorted(licznik.items(), key=lambda x: -x[1]))
Zarządzanie kosztami
class MenadzerKosztow:
def __init__(self, budzet_dzienny: float = 50.0):
self.budzet = budzet_dzienny
self.wydane_dzis = 0.0
self.data_resetu = datetime.now().date()
def mozna_wykonac(self, szacowany_koszt: float) -> bool:
"""Sprawdza, czy budżet pozwala na wykonanie."""
dzisiaj = datetime.now().date()
if dzisiaj > self.data_resetu:
self.wydane_dzis = 0.0
self.data_resetu = dzisiaj
return (self.wydane_dzis + szacowany_koszt) <= self.budzet
def zarejestruj_wydatek(self, koszt: float):
self.wydane_dzis += koszt
def pozostaly_budzet(self) -> float:
return self.budzet - self.wydane_dzis
# Integracja z orkiestratorem
menadzer_kosztow = MenadzerKosztow(budzet_dzienny=100.0)
def wykonaj_z_budzetem(orkiestrator, zapytanie, **kwargs):
szacowany_koszt = 0.05 # Zachowawcze oszacowanie
if not menadzer_kosztow.mozna_wykonac(szacowany_koszt):
return {"blad": "Osiągnięto dzienny budżet", "pozostalo": 0}
wynik = orkiestrator.wykonaj(zapytanie, **kwargs)
rzeczywisty_koszt = wynik["slad"].laczna_liczba_tokenow * 0.000002
menadzer_kosztow.zarejestruj_wydatek(rzeczywisty_koszt)
return wynik
Wzorzec: inteligentny router
Gdy przypadki użycia się mnożą, pojawia się pokusa, by wszystko przekazywać jednemu systemowi wyposażonemu we wszystkie narzędzia. To najdroższy wybór: każde żądanie, nawet trywialne, niesie ze sobą pełny zestaw definicji narzędzi. Router, który najpierw klasyfikuje żądanie, a następnie wywołuje wyspecjalizowanego orkiestratora, utrzymuje krótkie konteksty i pozwala mierzyć każdy przepływ osobno.
class InteligentnyRouter:
def __init__(self):
self.klient = OpenAI()
self.orkiestratory = {}
def zarejestruj(self, domena: str, orkiestrator: OrkiestratorProdukcji):
self.orkiestratory[domena] = orkiestrator
def kieruj(self, zapytanie: str) -> dict:
"""Określa domenę i kieruje do właściwego orkiestratora."""
# Szybka klasyfikacja za pomocą lekkiego modelu
odpowiedz = self.klient.responses.create(
model="gpt-5.6-terra",
input=f"Skategoryzuj to żądanie do domeny: {zapytanie}\n"
f"Dostępne domeny: {list(self.orkiestratory.keys())}\n"
f"Odpowiedz wyłącznie nazwą domeny.",
)
domena = odpowiedz.output_text.strip().lower()
if domena not in self.orkiestratory:
domena = "ogolna" # Fallback
logger.info(f"Żądanie skierowane do: {domena}")
return self.orkiestratory[domena].wykonaj(zapytanie)
# Konfiguracja
router = InteligentnyRouter()
router.zarejestruj("sprzedaz", OrkiestratorProdukcji(konfiguracja_asystenta_sprzedazy))
router.zarejestruj("wsparcie", OrkiestratorProdukcji(konfiguracja_wsparcia))
router.zarejestruj("hr", OrkiestratorProdukcji(konfiguracja_hr))
# Użycie
wynik = router.kieruj("Ile dni urlopu mi jeszcze zostało?")
# -> Automatycznie kieruje do orkiestratora HR
Lista kontrolna produkcyjna
Ta lista jest celowo krótka. Nie dąży do wyczerpania tematu, ale pokrywa punkty, których brak kosztuje Cię incydentami, a nie tylko dyskomfortem – i których nie dodasz w pośpiechu, gdy system będzie już w rękach użytkowników.
lista_kontrolna = {
"bezpieczenstwo": [
"Waliduj argumenty dla każdej funkcji",
"Limitowanie częstotliwości per użytkownik",
"Sanityzacja wejść i wyjść",
"Brak danych wrażliwych w logach"
],
"niezawodnosc": [
"Ponawianie z wycofaniem przy błędach przejściowych",
"Wyłącznik awaryjny per usługa zewnętrzna",
"Timeout per narzędzie i per globalne żądanie",
"Mechanizm fallback, gdy narzędzie jest niedostępne"
],
"wydajnosc": [
"Równoległe wykonanie niezależnych wywołań",
"Cache dla częstych wyników wyszukiwania",
"Ograniczenie liczby iteracji pętli",
"Dobór modelu adekwatnego do złożoności (gpt-5.6-terra vs gpt-5.6-terra)"
],
"obserwowalnosc": [
"Strukturalne logowanie każdego wywołania",
"Metryki opóźnienia i kosztów",
"Alerty przy wzroście wskaźnika błędów",
"Pełny ślad każdego żądania"
],
"koszty": [
"Dzienny budżet z wyłącznikiem awaryjnym",
"Szacowanie kosztu przed wykonaniem",
"Tygodniowy raport wydatków",
"Optymalizacja wyboru modelu w zależności od złożoności"
]
}
Kluczowe wnioski
- Rozłóż system na warstwy: interfejs, orkiestracja, wykonanie, obserwowalność
- Używaj konfiguracji deklaratywnej do definiowania systemów
- Śledź każde wykonanie dla celów monitorowania i debugowania
- Wdróż menedżera kosztów z dziennym budżetem
- Inteligentny router rozdziela żądania do właściwych orkiestratorów
Sprawdź swoją wiedzę
Wywoływanie funkcji, wyszukiwanie, wykonanie: pełen arsenał w pięciu pytaniach.
1. Co powinien zawierać dobry schemat funkcji?
Odpowiedź: Ścisłe typy i operacyjne opisy dla każdego parametru – to kontrakt, którego model używa, by zdecydować, kiedy wywołać funkcję i jak ją wypełnić; walidacja odrzuca resztę.
2. Wyszukiwanie w sieci czy wyszukiwanie w plikach: jak wybrać?
Odpowiedź: Wyszukiwanie w sieci dla publicznych, świeżych informacji; wyszukiwanie w plikach dla Twoich zindeksowanych dokumentów (chunking + wbudowane rankingi) – a wyszukiwanie hybrydowe łączy oba podejścia, gdy odpowiedź obejmuje oba światy.
3. Co umożliwia Code Interpreter w API?
Odpowiedź: Wykonywanie kodu w piaskownicy: przetwarzanie CSV/Excel/obrazów, precyzyjne obliczenia, generowanie wykresów – model rozumuje, kod liczy, piaskownica izoluje.
4. Do czego służy Tool Search?
Odpowiedź: Do dynamicznego udostępniania dużego katalogu narzędzi: model wyszukuje odpowiednie narzędzie zamiast otrzymywać setki schematów naraz – kontekst pozostaje lekki, możliwości pozostają rozległe.
5. Jakie zasady obowiązują w architekturze wielonarzędziowej w środowisku produkcyjnym?
Odpowiedź: Narzędzia o jasnym zakresie, obsługa błędów i mechanizmy fallback per narzędzie, równoległe wywołania, gdy są niezależne, oraz obserwowalność każdego wywołania – odporność projektuje się narzędzie po narzędziu.
Każde narzędzie ma swój teren; środowisko produkcyjne je łączy – powyższa architektura końcowa jest Twoim planem referencyjnym.