Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Cruthaigh Gníomhaíocht

Ceacht 4 as 14 Nuashonraithe 2 Samhain 2026 Ardleibhéal
Ar an leathanach seo
  1. Cad é Gníomhaíocht?
  2. Anatamaíocht Gníomhaíochta
  3. Samplaí Coincréiteacha Gníomhaíochtaí
  4. Saintréithe Bunúsacha
  5. Gníomhaíocht a Ainmniú
  6. Srian Méide
  7. Príomhphointí

Cad é Gníomhaíocht?

Is í an ghníomhaíocht an t-aonad oibríochta bunúsach i sreabhadh oibre. Anseo a dhéantar an obair iarbhír: glaonna ar API seachtracha, ceisteanna bunachair sonraí, seoladh ríomhphoist, próiseáil comhad, agus glaonna ar mhúnlaí AI. Tá an roinnt oibre simplí agus beidh sí mar threoir agat ar fud an chúrsa seo: caithfear aon oibríocht a bhaineann le hionchur/aschur (I/O) nó le fo-iarsmaí a chapsúlú i ngníomhaíocht.

Cé go ndéanann an sreabhadh oibre comhordú, feidhmíonn an ghníomhaíocht. Sin an difríocht bhunúsach, agus tá tionchar díreach aige air sin: toisc go bhfuil obair rioscach leithlisithe laistigh de ghníomhaíochtaí, is féidir leis an inneall iarracht a dhéanamh arís, tomhas a dhéanamh, agus athsheinm gan fo-iarsmaí a dhúbailt riamh.

Anatamaíocht Gníomhaíochta

Is feidhm Python async í gníomhaíocht atá maisithe leis an maisitheoir @workflows.activity():

import mistralai.workflows as workflows

@workflows.activity()
async def get_user_profile(user_id: str) -> dict:
    """Retrieves a user profile from the API."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        response.raise_for_status()
        return response.json()

Tá ceithre eilimint sna línte beaga seo a thuilleann do aire. Cláraíonn an maisitheoir @workflows.activity() an fheidhm mar ghníomhaíocht leis an inneall, rud a fhágann gur féidir glaoch uirthi ó shreabhadh oibre. Tá async def éigeantach: caithfidh gach gníomhaíocht a bheith asioncronach, gan eisceacht. Caithfidh paraiméadair a bheith in-sraitheáilte mar JSON, rud a chiallaíonn cineálacha simplí—str, int, float, bool, list, dict—nó samhlacha Pydantic; teipfidh ar shraitheá má thugtar oibiacht nasctha nó láimhseálaí comhaid mar argóint. Baineann an riail chéanna leis an luach a thuirtear, a thaistealaíonn tríd an líonra sula scríobhtar é chuig log na n-imeachtaí.

Samplaí Coincréiteacha Gníomhaíochtaí

Is é an chéad chás, is dócha an ceann is coitianta sa chúrsa seo, ná glaonn ar mhúnla Mistral a chapsúlú. Tabhair faoi deara go dtugann an ghníomhaíocht tomhaltas token ar ais freisin: nuair a bheidh sé sa log, ligeann an cineál seo meiteashonraí duit costas feidhmithe a athchruthú i ndiaidh an fhíric.

import mistralai.workflows as workflows
from mistralai.client import Mistral

@workflows.activity()
async def generate_summary(text: str) -> dict:
    """Generates a summary of the provided text via Mistral."""
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "You are an assistant specialized in text summarization."},
            {"role": "user", "content": f"Summarize this text in 3 sentences:\n\n{text}"}
        ]
    )
    return {
        "summary": response.choices[0].message.content,
        "tokens_used": response.usage.total_tokens
    }

Léiríonn an dara cás rochtain ar bhunachar sonraí. Níl an bloc try/finally maisiúil: má theipeann ar an ngníomhaíocht agus má dhéantar iarracht arís, ídeoidh nasc oscailte a fhágáil ar gach iarracht linn PostgreSQL go tapa.

import mistralai.workflows as workflows
import asyncpg

@workflows.activity()
async def save_report(report: dict) -> dict:
    """Saves a report to PostgreSQL."""
    conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
    try:
        row = await conn.fetchrow(
            "INSERT INTO reports (title, content, created_at) VALUES ($1, $2, NOW()) RETURNING id",
            report["title"],
            report["content"]
        )
        return {"id": row["id"], "status": "saved"}
    finally:
        await conn.close()

Is é an tríú cás, seoladh ríomhphoist, an áit a bhfuil fo-iarsmaí le feiceáil go soiléir: nuair a sheoltar an teachtaireacht, ní féidir le haon iarracht arís í a ghabháil.

import mistralai.workflows as workflows
import aiosmtplib

@workflows.activity()
async def send_notification(recipient: str, subject: str, body: str) -> dict:
    """Sends a notification email."""
    message = f"Subject: {subject}\nTo: {recipient}\n\n{body}"
    await aiosmtplib.send(
        message,
        hostname="smtp.example.com",
        port=587,
        username="[email protected]",
        password="secret",
        use_tls=True
    )
    return {"status": "sent", "recipient": recipient}

Saintréithe Bunúsacha

Ar an gcéad dul síos, saoirse fáilteach: murab ionann agus sreabhadh oibre, níl aon srianta cinnteachta ar ghníomhaíochtaí. Is féidir leat datetime.now(), uuid.uuid4(), random.random(), nó aon ghlao neamhchinnteach eile a úsáid go saor laistigh de ghníomhaíocht. Sin díreach an rud atá gníomhaíochtaí ann dóibh—gach rud a cheadaítear don sreabhadh oibre a ionsú.

Ansin, déileálann an ardán le gach glao gníomhaíochta mar aonad adamhach: éiríonn leis go hiomlán nó teipeann air go hiomlán, gan aon staid idirmheánach le feiceáil ag an sreabhadh oibre. Má dhéanann do ghníomhaíocht trí rud agus má thuairteálann an dara ceann, ní fheiceann an sreabhadh oibre ach teip, ní rath páirteach. Sin an fáth ar chóir duit seachaint cúig oibríocht ar leith a charnadh i bhfeidhm amháin.

Nuair a éiríonn le gníomhaíocht, déantar a toradh a thaifeadadh go buan i log imeachtaí an tsreabha oibre. Le linn athsheinmte, ní fheidhmítear an ghníomhaíocht arís riamh: ní úsáidtear ach an toradh taifeadta. Mar mhalairt air sin, toisc go bhféadfar iarracht a dhéanamh ar ghníomhaíocht arís má theipeann uirthi—am-teorainn líonra, earráid thréimhseach—caithfidh sí a bheith idempotach: má fheidhmítear í uaireanta iomadúla leis na paraiméadair chéanna, caithfidh sí an toradh céanna a tháirgeadh. Is minic go leor a bheith ag athrú ó POST go PUT ar aitheantóir cobhsaí chun an airí seo a bhaint amach, mar atá anseo áit a bhfeidhmíonn an ríomhphost mar eochair:

@workflows.activity()
async def create_or_update_client(email: str, name: str) -> dict:
    """Idempotent: uses an upsert instead of an insert."""
    async with httpx.AsyncClient() as client:
        response = await client.put(
            f"https://api.crm.com/clients/{email}",
            json={"name": name, "email": email}
        )
        return response.json()

Gníomhaíocht a Ainmniú

Glacann an maisitheoir le hainm sainráite, rud a fheabhsaíonn inléiteacht an rianaithe go mór nuair a bhíonn ainm teicniúil Béarla ar fheidhm nach mbaineann aon duine eile ar an bhfoireann leis an bhfearann gnó:

@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
    # ...
    pass

Beidh an t-ainm seo le feiceáil i rianta OpenTelemetry agus éascóidh sé dífhabhtú. Déan cleachtas de é a shocrú ón tús: an lá a bheidh tú ag lorg an fáth ar thóg feidhmiú daichead nóiméad, léifidh tú lipéid chiallmhara seachas liosta d’ainmneacha feidhme.

Srian Méide

Rialaíonn dhá theorainn malartuithe: 2 MB ar a mhéad do pharaiméadair ionchuir agus 2 MB ar a mhéad don luach a thuirtear. Tagann siad seo go díreach ó fhoinsiú imeachtaí, ós rud é go ndéantar na luachanna seo a shraitheáil agus a stóráil sa log.

Tá an toradh praiticiúil soiléir. Má tá ort comhaid mhóra a phróiseáil—PDF scantha 40 MB, cartlann onnmhairithe—ná cuir iad ó ghníomhaíocht go gníomhaíocht. Stóráil iad i seirbhís sheachtrach (S3, GCS) agus ní chuir ach an URL nó an t-aitheantóir i gcúrsaíocht: íoslódálann an ghníomhaíocht an comhad, próiseálann sé é, scríobhann sé an toradh ar ais chuig an stóráil, agus filleann sé tagairt de roinnt céadta beart.

Príomhphointí

  • Is feidhm async í gníomhaíocht atá maisithe le @workflows.activity() a dhéanann an obair iarbhír (I/O, API, DB)
  • Caithfidh paraiméadair agus luachanna tuairisceana a bheith in-sraitheáilte mar JSON
  • Níl aon srianta cinnteachta ar ghníomhaíochtaí
  • Ní fheidhmítear gníomhaíocht rathúil arís riamh le linn athsheinmte
  • Caithfidh gníomhaíochtaí a bheith idempotach (an toradh céanna má fheidhmítear iad uaireanta iomadúla)
  • Teorainn 2 MB ar ionchur agus aschur in aghaidh na gníomhaíochta