Executarea și testarea unui flux de lucru
Pe această pagină
Lecție actualizată la 3 noiembrie 2026 pe baza SDK-ului
mistralai3.7.0: urmărirea unei execuții utilizează acumclient.workflows.executions.get_workflow_execution_async, iar rezultatul se citește dinresult. Addendum din aceeași zi: exemplele anterioare făceau referire laexecution.id,execution.outputșiexecution.error, care sunt absente din SDK, și comparau starea cu valorile în litere mici"completed"sau"failed"; acum se utilizeazăexecution_id,result,wait_for_result=Trueși stări cu litere mari. Sursă: client-python.
Declanșarea unui flux de lucru
Ați scris activitățile, ați definit fluxul de lucru și ați pornit worker-ul. Acum trebuie să lansați o execuție. Aveți două opțiuni: SDK-ul Python sau o apelare cURL către API-ul REST. Prima se potrivește scripturilor și serviciilor dumneavoastră Python; a doua funcționează pentru teste rapide din linia de comandă sau declanșări din sisteme non-Python—un webhook, un planificator sau un backend scris într-un alt limbaj.
Trebuie îndeplinite trei condiții înainte de a declanșa orice. Worker-ul dumneavoastră trebuie să fie în execuție (uv run python worker.py), cheia API trebuie setată în MISTRAL_API_KEY, iar fluxul de lucru trebuie să fie înregistrat la acel worker, ceea ce înseamnă că apare în lista transmisă către run_worker().
Declanșarea prin SDK-ul Python
Scrieți declanșatorul într-un script separat de worker, deoarece procesul worker-ului nu returnează niciodată controlul:
import asyncio
from mistralai.client import Mistral
async def main():
client = Mistral()
execution = await client.workflows.execute_workflow_async(
workflow_identifier="salutation_workflow",
input={"nom": "Marie"},
wait_for_result=True, # așteaptă finalizarea și primește rezultatul
)
print(f"Execution ID: {execution.execution_id}")
print(f"Result: {execution.result}")
if __name__ == "__main__":
asyncio.run(main())
Parametrul workflow_identifier corespunde exact cu name declarat în @workflows.workflow.define(), iar cheile din dicționarul input corespund parametrilor metodei dumneavoastră run. Rulați acest script într-un terminal separat, lăsându-l pe primul ocupat de worker:
uv run python trigger.py
Cu wait_for_result=True, SDK-ul așteaptă finalizarea execuției și returnează rezultatul direct, făcând testarea foarte lizibilă pentru fluxurile de lucru scurte. Fără acest parametru, apelul returnează imediat identificatorul execuției, pe care îl veți urmări apoi (vezi mai jos).
Declanșarea prin cURL
Pentru teste rapide sau integrarea cu alte sisteme, API-ul REST expune același declanșator:
curl -X POST https://api.mistral.ai/v1/workflows/salutation_workflow/execute \
-H "Authorization: Bearer $MISTRAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"nom": "Marie"}, "wait_for_result": true}'
Cu wait_for_result, răspunsul conține numele fluxului de lucru, identificatorul execuției și rezultatul său; acestea sunt câmpurile modelului WorkflowExecutionSyncResponse din SDK:
{
"workflow_name": "salutation_workflow",
"execution_id": "…",
"result": {
"message": "Bonjour, Marie !"
}
}
Păstrați acest execution_id: este cheia pe care o veți folosi ulterior pentru a interoga execuția sau pentru a recupera urmele sale. Fără wait_for_result, răspunsul descrie execuția în curs de desfășurare, inclusiv starea sa (RUNNING inițial).
Exemplu cap-la-cap
Să reluăm exemplul pipeline-ului de analiză a documentelor, de data aceasta complet configurat. Primul fișier combină definițiile și pornirea worker-ului; rețineți trunchierea la 5000 de caractere, care protejează atât limita de dimensiune a activității, cât și bugetul dumneavoastră de tokeni.
Fișierul workflow.py (worker + definiții)
import asyncio
import httpx
import mistralai.workflows as workflows
from mistralai.client import Mistral
@workflows.activity()
async def extraire_texte(url: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(url)
return {"texte": response.text[:5000]} # Limitare la 5000 de caractere
@workflows.activity()
async def resumer_texte(texte: str) -> dict:
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Summarize in 3 sentences."},
{"role": "user", "content": texte}
]
)
return {"resume": response.choices[0].message.content}
@workflows.workflow.define(name="resume_page_web")
class ResumePageWeb:
@workflows.workflow.entrypoint
async def run(self, url: str) -> dict:
extraction = await extraire_texte(url)
resume = await resumer_texte(extraction["texte"])
return {
"url_source": url,
"resume": resume["resume"]
}
async def main() -> None:
await workflows.run_worker([ResumePageWeb])
if __name__ == "__main__":
asyncio.run(main())
Al doilea fișier declanșează fluxul de lucru și afișează rezultatul, gestionând explicit cazul eșecului—un reflex de adoptat încă de la primul script:
Fișierul trigger.py (declanșator)
import asyncio
from mistralai.client import Mistral
async def main():
client = Mistral()
print("Lansare flux de lucru...")
execution = await client.workflows.execute_workflow_async(
workflow_identifier="resume_page_web",
input={"url": "https://example.com/article"},
)
print(f"Execuție lansată: {execution.execution_id}")
# Urmărește execuția până la finalizare
while True:
suivi = await client.workflows.executions.get_workflow_execution_async(
execution_id=execution.execution_id
)
if suivi.status not in ("RUNNING", "RETRYING_AFTER_ERROR"):
break
await asyncio.sleep(2)
if suivi.status == "COMPLETED":
print(f"Rezumat: {suivi.result['resume']}")
else:
print(f"Execuție finalizată cu starea {suivi.status}")
if __name__ == "__main__":
asyncio.run(main())
Execuția
Terminalul 1 — Porniți worker-ul:
uv run python workflow.py
Terminalul 2 — Declanșați execuția:
uv run python trigger.py
Verificarea rezultatelor
Terminalul worker-ului este primul dumneavoastră punct de observație: acesta afișează activitățile executate în timp real, împreună cu durata lor, arătându-vă imediat care pas consumă cel mai mult timp.
[INFO] Executing activity: extraire_texte
[INFO] Activity completed: extraire_texte (1.2s)
[INFO] Executing activity: resumer_texte
[INFO] Activity completed: resumer_texte (3.4s)
[INFO] Workflow completed: resume_page_web
Pentru fluxurile de lucru lungi, evident că nu veți rămâne lipit de terminal. Odată ce aveți ID-ul execuției, puteți interoga starea sa în orice moment dintr-un alt proces:
execution = await client.workflows.executions.get_workflow_execution_async(
execution_id="exec_abc123"
)
print(f"Status: {execution.status}")
print(f"Result: {execution.result}")
Aceeași operațiune este disponibilă prin cURL, utilă într-un script de monitorizare:
curl https://api.mistral.ai/v1/workflows/executions/exec_abc123 \
-H "Authorization: Bearer $MISTRAL_API_KEY"
Gestionarea erorilor
O defecțiune nu apare la prima excepție: platforma reîncearcă mai întâi activitatea conform politicii sale de reîncercare. Doar după epuizarea reîncercărilor, execuția trece în starea FAILED (stările SDK sunt cu litere mari: RUNNING, COMPLETED, FAILED, CANCELED, TERMINATED, TIMED_OUT etc.), iar codul dumneavoastră apelant trebuie să gestioneze acest caz în loc să presupună că un result este întotdeauna prezent:
execution = await client.workflows.executions.get_workflow_execution_async(
execution_id="exec_abc123"
)
if execution.status == "FAILED":
print(f"Execuția {execution.execution_id} a eșuat")
Răspunsul nu conține un mesaj de eroare: cauza apare în istoricul execuției și în jurnale (get_workflow_execution_history_async, get_workflow_execution_logs_async). Pentru a identifica activitatea defectuoasă și secvența care a dus la aceasta, veți analiza urmele OpenTelemetry, acoperite în Lecția 14.
Testarea locală
Naveta între două terminale devine rapid obositoare în timpul dezvoltării. Pentru dezvoltare, un singur script poate porni worker-ul în fundal, poate declanșa fluxul de lucru și apoi poate opri totul:
import asyncio
import mistralai.workflows as workflows
# ... definiții activitate și flux de lucru ...
async def main():
# Pornește worker-ul în fundal
worker_task = asyncio.create_task(
workflows.run_worker([MonWorkflow])
)
# Așteaptă ca worker-ul să fie gata
await asyncio.sleep(2)
# Declanșează fluxul de lucru
from mistralai.client import Mistral
client = Mistral()
execution = await client.workflows.execute_workflow_async(
workflow_identifier="mon_workflow",
input={"test": True},
wait_for_result=True,
)
print(f"Result: {execution.result}")
# Oprește worker-ul
worker_task.cancel()
if __name__ == "__main__":
asyncio.run(main())
Funcția asyncio.sleep(2) oferă worker-ului timp să stabilească conexiunea înainte de declanșare, iar worker_task.cancel() final previne blocarea indefinită a scriptului. Rezervați această configurare pentru dezvoltare: în producție, worker-ul și declanșatoarele rămân procese separate cu cicluri de viață independente.
Puncte cheie
- Două metode de declanșare: SDK Python (
execute_workflow_async) și API REST (cURL) - Worker-ul trebuie să ruleze pentru ca fluxul de lucru să se execute
- Cu
wait_for_result=True, SDK-ul așteaptă finalizarea și returnează rezultatul (result); altfel returneazăexecution_idpentru urmărire - Utilizați
client.workflows.executions.get_workflow_execution_async()pentru a verifica starea unei execuții - Stările sunt cu litere mari (
RUNNING,COMPLETED,FAILEDetc.); cauzele eșecurilor apar în istoricul execuției, jurnale și urme - Pentru dezvoltare, combinați worker-ul și declanșatorul într-un singur script folosind
asyncio