Ez a Cloudflare Workers AI útmutató bemutatja, hogyan telepíthet és futtathat gépi tanulási modelleket közvetlenül a Cloudflare globális edge hálózatán. A Cloudflare Workers AI segítségével nagy nyelvi modelleket (LLM), szövegfordítást, képgenerálást és hangátírást futtathat a felhasználók közelében, összetett és drága GPU szerverek üzemeltetése nélkül. Az alábbi lépésekből megtudhatja, hogyan konfigurálhatja a Wrangler-t, hogyan írhat fetch handlert, futtathat Llama modellt, és hogyan optimalizálhatja az API költségeket az edge hálózaton.

TL;DR

  • MI modellek futtatása szerver nélkül: A Cloudflare Workers AI kezeli a mögöttes GPU infrastruktúrát, és csak az aktív számítási időért számláz.
  • Kötések (bindings) konfigurálása a wrangler.toml fájlban: Csatlakoztassa Workerét közvetlenül az AI kötéshez API kulcsok kezelése nélkül.
  • Fetch handler írása a felhasználói kérések fogadására, a modell futtatására és a JSON válaszok streamelésére.
  • Optimalizált modellek kiválasztása a Cloudflare katalógusából (például Llama 3, Whisper vagy Stable Diffusion) a sebesség és a pontosság egyensúlyának megteremtéséhez.
  • Lekérdezési korlátok bevezetése a végpontok védelmére, elkerülve a magas token-költségű visszaéléseket éles környezetben.

Miért érdemes MI modelleket az edge hálózaton futtatni?

Hagyományosan az MI-funkciók integrálásához külső API-kat (például OpenAI) kellett meghívni, vagy saját nyílt forráskódú modelleket kellett futtatni drága felhőszervereken.

A külső API-k hívása késleltetést okoz és adatvédelmi aggályokat vet fel. A saját GPU-szerverek üzemeltetése karbantartási nehézségekkel jár, és nehezen skálázható. A Cloudflare Workers AI megoldja ezt a dilemmát. A platform nyílt forráskódú modelleket hosztol a Cloudflare globális hálózatán telepített GPU-kon. A kódja könnyű Worker-ként fut, és a modelleket a felhasználók közelében hajtja végre, szinte nulla késleltetéssel. Az alapvető edge-struktúrák felépítéséről olvassa el a szerver nélküli API-k Cloudflare Workers-szel történő létrehozásáról szóló útmutatónkat.

Előfeltételek

Mielőtt elkezdené, győződjön meg arról, hogy rendelkezik a következőkkel:

  • Egy Cloudflare-fiók bekapcsolt Workers funkcióval. Az ingyenes csomag tartalmaz egy napi következtetési (inference) keretet, ami bőségesen elegendő az útmutató követéséhez.
  • Node.js 18 vagy újabb helyben telepítve a fejlesztői eszközök és a helyi fejlesztőszerver futtatásához.
  • Wrangler (a Workers CLI) telepítve és hitelesítve. Telepítse az npm install -g wrangler paranccsal, majd futtassa a wrangler login parancsot a fiókja összekapcsolásához.
  • Alapvető JavaScript ismeretek és a fetch kérés/válasz modell megértése, amelyre minden Worker épül.

Ha teljesen üres lappal indul, hozzon létre egy projektet a create-cloudflare (C3) eszközzel. Ez létrehoz egy azonnal telepíthető Worker-t, a wrangler.toml fájlt és a megfelelő compatibility_date-et:

1npm create cloudflare@latest my-edge-ai
2cd my-edge-ai

Válassza a “Hello World” Worker sablont, amikor a rendszer kéri. Ez egy tiszta kiindulópontot biztosít, amelyhez a következő lépésben hozzáadhatja az AI kötést.

1. lépés: A wrangler.toml konfigurálása

Az MI modellek eléréséhez először meg kell határoznia az AI kötést a projekt konfigurációs fájljában.

Nyissa meg a wrangler.toml (vagy wrangler.json) fájlt, és adja hozzá a következő blokkot:

1[ai]
2binding = "AI"

Ez a kötés elérhetővé teszi az AI szolgáltatást a környezeti argumentumban (env.AI) a Worker kódjában. Nem kell API kulcsokat kezelnie, végpontokat konfigurálnia vagy kapcsolatleírókkal bajlódnia. A Wrangler automatikusan kezeli a hitelesítést a telepítés során.

A projekt teljes wrangler.toml fájlja így néz ki:

1name = "my-edge-ai"
2main = "src/index.js"
3compatibility_date = "2025-01-01"
4
5[ai]
6binding = "AI"

A compatibility_date fontos: rögzíti a futtatókörnyezet viselkedését, így a jövőbeli platformváltozások nem módosíthatják váratlanul a Worker működését. Ha kihagyja, a telepítés konfigurációs hibával meghiúsul – ez az egyik leggyakoribb hiba az első futtatáskor.

2. lépés: A Worker kód megírása

A kötés konfigurálása után meghívhatja az AI szolgáltatást a fetch handlerből. Az alábbi példa bemutatja, hogyan fogadhat egy felhasználói promptot tartalmazó JSON-t, és hogyan generálhat szöveges választ a Llama 3 segítségével.

 1export default {
 2  async fetch(request, env) {
 3    if (request.method !== "POST") {
 4      return new Response("Method not allowed", { status: 405 });
 5    }
 6
 7    try {
 8      const { prompt } = await request.json();
 9      if (!prompt) {
10        return Response.json({ error: "Missing prompt" }, { status: 400 });
11      }
12
13      // Call the model using the AI binding
14      const response = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
15        prompt: prompt,
16        max_tokens: 256
17      });
18
19      return Response.json(response);
20    } catch (err) {
21      return Response.json({ error: err.message }, { status: 500 });
22    }
23  }
24};

Ez az egyszerű struktúra lehetővé teszi szöveges összegzők, érzelemelemző eszközök vagy tartalomgenerátorok építését. Ha szeretné összekapcsolni ezeket a funkciókat az adatbázisával, hozzákapcsolhatja egy szerver nélküli SQL-adatbázishoz; a részletekért lásd a Cloudflare D1 adatbázis beállítását .

A chat üzenetformátum használata

A prompt mező kényelmes az egyszeri válaszokhoz, de a társalgási modellek a strukturált messages tömbbel működnek a legjobban. Ez lehetővé teszi, hogy beállítson egy rendszerutasítást (system prompt), amely meghatározza a modell stílusát, és elkülöníti azt a felhasználó bemenetétől:

 1const messages = [
 2  { role: "system", content: "You are a concise technical assistant." },
 3  { role: "user", content: prompt }
 4];
 5
 6const response = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
 7  messages,
 8  max_tokens: 512
 9});
10
11// Text models return the generated text on the `response` property
12return Response.json({ answer: response.response });

Vegye figyelembe, hogy a szöveggeneráló modellek a kimenetüket egy response mezőbe csomagolják, így a kész szöveg a response.response alatt érhető el, nem pedig a legfelső szinten. Ez sok első alkalommal fejlesztőt megtéveszt, akik a nyers objektum kiíratásakor váratlan struktúrát látnak.

A megfelelő modell kiválasztása

A Cloudflare katalógusa több tucat modellt tartalmaz, és a választás a sebesség, a minőség és a költség közötti kompromisszum. A kisebb modellek gyorsabban válaszolnak és kevesebb erőforrást fogyasztanak; a nagyobb modellek jobban gondolkodnak, de lekérdezésenként többe kerülnek. Az alábbi táblázat összehasonlít néhány népszerű szöveggenerálási lehetőséget.

ModellLegjobb felhasználási területRelatív sebességRelatív költség
@cf/meta/llama-3-8b-instructÁltalános chat, összegzésGyorsAlacsony
@cf/meta/llama-3.1-70b-instructÖsszetett logikai feladatok, hosszú válaszokLassabbMagasabb
@cf/mistral/mistral-7b-instruct-v0.2Könnyű utasítások, piszkozatokGyorsAlacsony
@cf/meta/llama-guard-3-8bTartalom moderálása és osztályozásaGyorsAlacsony

Ökölszabályként kezdjen egy 8B modellel, mint például a Llama 3 8B Instruct. Ez kezeli az összegzési, osztályozási és chat feladatok többségét egy 70B modell késleltetésének és költségének töredékéért. Csak akkor váltson nagyobb modellre, ha a saját tesztjei alapján a kisebb modell valóban alulteljesít.

3. lépés: Válaszok streamelése a jobb felhasználói élményért

Chat-alkalmazások esetében a teljes válasz generálására való várakozás rossz felhasználói élményt eredményezhet.

Konfigurálhatja az AI kötést úgy, hogy a választ tokenenként streamelje generálás közben. Ehhez adja át a stream: true paramétert a kérés beállításaiban. A Worker egy ReadableStream-et ad vissza, amelyet közvetlenül továbbíthat a böngészőnek, így egy gyors, interaktív chat-felületet hozhat létre. Az edge futtatókörnyezet és a hagyományos felhőalapú hosztolás összehasonlításához olvassa el a Cloudflare Workers vs. AWS Lambda elemzésünket.

Itt egy teljes streamelő handler. Ahelyett, hogy feldolgozott JSON-t adna vissza, a streamet közvetlenül továbbítja a kliensnek a megfelelő content-type beállítással, így a böngésző Server-Sent Events-ként tudja azt fogadni:

 1export default {
 2  async fetch(request, env) {
 3    const { prompt } = await request.json();
 4
 5    const stream = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
 6      prompt,
 7      max_tokens: 512,
 8      stream: true
 9    });
10
11    return new Response(stream, {
12      headers: { "content-type": "text/event-stream" }
13    });
14  }
15};

A kulcsfontosságú különbség a nem streamelő verzióhoz képest maga a válasz: a streamet közvetlenül átadja a new Response()-nak, és a content-type fejlécet text/event-stream értékre állítja. Ha a streamet a Response.json() fájlba csomagolná, az nem szerializálódna megfelelően, és a kliens üres választ kapna.

A Worker tesztelése és telepítése

A kötés és a handler beállítása után futtassa a Worker-t helyben, mielőtt élesítené:

1npx wrangler dev

Mivel a következtetés (inference) a Cloudflare GPU-in fut, nem pedig a saját gépén, az AI kötés a hálózathoz kapcsolódik a helyi fejlesztés során is. A Wrangler ezt kezeli Ön helyett, de ez azt jelenti, hogy a helyi teszteléshez internetkapcsolatra és érvényes bejelentkezésre van szükség.

Küldjön egy tesztkérést a curl segítségével, miközben a wrangler dev fut:

1curl -X POST http://localhost:8787 \
2  -H "Content-Type: application/json" \
3  -d '{"prompt": "Summarise the benefits of edge computing in one sentence."}'

Ha elégedett az eredménnyel, telepítse a globális hálózatra:

1npx wrangler deploy

A Wrangler feltölti a Worker-t, és visszaad egy *.workers.dev URL-t. A végpontja mostantól a Cloudflare minden adatközpontjában él, és minden kérés automatikusan a felhasználóhoz legközelebbi helyre irányítódik.

Gyakori hibák és hibaelhárítás

Néhány probléma gyakran előfordul, amikor a fejlesztők először telepítenek következtetési folyamatokat az edge hálózaton. A megoldások ismerete órákig tartó hibakeresést takaríthat meg.

  • Cannot read properties of undefined (reading 'run') – az env.AI kötés nincs definiálva. Ez szinte mindig azt jelenti, hogy az [ai] blokk hiányzik a wrangler.toml fájlból, vagy módosította a fájlt, de nem indította újra a wrangler dev parancsot. Ellenőrizze, hogy a kötés neve pontosan egyezik-e.
  • No such model vagy 400-as hiba a run során – a modell azonosítója hibás. A modellnevek megkülönböztetik a kis- és nagybetűket, és tartalmazniuk kell a teljes elérési utat, például @cf/meta/llama-3-8b-instruct. Másolja ki őket a modellkatalógusból, ahelyett, hogy fejből gépelné be őket.
  • Üres vagy hibás streamelt válaszok – a streamet a Response.json() segítségével adta vissza a new Response(stream, ...) helyett. A streameket továbbítani kell, nem pedig szerializálni.
  • Kapacitási vagy 429-es hibák terhelés alatt – a modell átmenetileg túlterhelt, vagy elérte a fiók korlátját. Adjon hozzá egy rövid újrapróbálkozási logikát késleltetéssel (back-off), és fontolja meg egy kisebb modell használatát a forgalmi csúcsok idejére.
  • Csonka válaszok – a válasz mondat közben leáll, mert a max_tokens túl alacsony. Emelje meg a korlátot, de ne feledje, hogy a nagyobb értékek növelik a késleltetést és a költségeket is.

Ha egy kérés hiba nélkül leáll, ellenőrizze a naplókat az npx wrangler tail paranccsal, miközben tesztkérést küld. Ez valós időben közvetíti a futásidejű hibákat és a console.log kimeneteket a telepített Workerből.

Költségoptimalizálás és biztonság éles környezetben

Bár a Workers AI rendkívül költséghatékony, az éles környezetben történő futtatás gondos kontrollt igényel.

  • Lekérdezési korlátozás (Rate Limiting): Korlátozza, hogy egy kliens milyen gyakran hívhatja meg a végpontot. A GPU számítási költségek a használattal arányosan skálázódnak.
  • Promptek ellenőrzése: Validálja a bemeneteket a prompt injection támadások megelőzése érdekében, és biztosítsa, hogy a modell kimenetei megfeleljenek a márka elvárásainak.
  • Kontextusméret korlátozása: Tartsa röviden a prompt előzményeket. A hatalmas kontextuspufferek küldése minden hívásnál növeli a tokenfeldolgozási költségeket.

A kontextuskezelés részletes leírását megtalálja az OpenAI API chatbot készítéséről szóló útmutatónkban.

Legfontosabb tanulságok

  • A Cloudflare Workers AI szerver nélküli hozzáférést biztosít a nyílt forráskódú modellekhez GPU karbantartás nélkül.
  • Konfigurálja a hozzáférést az [ai] kötési blokk hozzáadásával a wrangler.toml fájlhoz.
  • Írjon fetch handlereket szöveggenerálási, fordítási vagy képalkotási feladatok végrehajtásához közvetlenül az edge hálózaton.
  • Engedélyezze a token streamelést a stream: true paraméterrel a mobil- és chat-élmény optimalizálásához.
  • Alkalmazzon sebességkorlátozásokat és prompt-ellenőrzéseket a végpontok védelme érdekében éles környezetben.

Építse fel MI-alkalmazásait az edge hálózaton

A megbízható MI-integrációk kiépítése szakértői ismereteket igényel a szerver nélküli architektúrák terén. A Mecanik professzionális MI integrációs szolgáltatásokra és egyedi API-megoldásokra szakosodott az OpenAI API integrációs szolgáltatásunkon keresztül. Olyan edge-natív eszközöket építünk, amelyek zökkenőmentesen skálázódnak, optimalizálva a költségeket és a felhasználói élményt. Vegye fel velünk a kapcsolatot a részletek egyeztetéséhez.

Gyakran ismételt kérdések (GYIK)

Mi az a Cloudflare Workers AI? Ez egy szerver nélküli platform, amely lehetővé teszi gépi tanulási modellek (szöveggenerálás, fordítás, hang-szöveg átalakítás, képgenerálás) futtatását a Cloudflare globális GPU hálózatán.

Szükségem van API kulcsra a Workers AI használatához? Nem. Miután deklarálta az AI kötést a wrangler.toml fájlban, a Cloudflare belsőleg kezeli a hitelesítést, így a szolgáltatás elérhetővé válik az env.AI segítségével.

Milyen modellek érhetők el a Cloudflare Workers AI-n? A platform népszerű nyílt forráskódú modelleket hosztol, beleértve a Meta Llama, Mistral, OpenAI Whisper és Stable Diffusion modelleket, amelyeket rendszeresen frissítenek a modellkatalógusban.

Streamelhetek szöveges válaszokat a Workers AI-ról? Igen. Ha az env.AI.run hívás paramétereiben beállítja a stream: true értéket, a Worker egy szabványos ReadableStream-et ad vissza a szöveg böngészőbe történő streameléséhez.

Hogyan működik a számlázás a Workers AI esetében? A számlázás a feldolgozott tokenek számán (szöveges modellek esetén) vagy a számítási idő hosszán (más modellek esetén) alapul, költséghatékony használatalapú modellt kínálva.