Unataka kupanga safari ya kwenda Goa. Una siku tano, bajeti ya rupia 25,000, na upendeleo wa wazi wa fukwe na vyakula vya baharini. Kawaida, hii inamaanisha kufungua tab kumi za kivinjari, kusoma machapisho ya zamani kwenye majukwaa, na kuunganisha ratiba kwa mkono. Badala yake, fikiria kutuma ombi moja la POST na kupata mpango uliopangwa siku kwa siku wenye mapendekezo ya milo, orodha ya shughuli, na mgawanyo sahihi wa bajeti. Hicho ndicho mradi huu unachotoa.

Tutajenga REST API kwa kutumia Spring Boot na Azure OpenAI. API hii inakubali mahali unapoenda, bajeti, muda, na mambo unayopenda. Inarudisha JSON safi ambayo programu ya mbele (frontend) au programu ya simu inaweza kuonyesha mara moja. Hakuna scraping. Hakuna ratiba zilizowekwa moja kwa moja (hardcoded). Ni modeli ya AI iliyoelekezwa kufanya kazi kama mpangaji wa safari.

Kile API Inachorudisha

Jibu si kifungu cha maandishi ya Markdown unayopaswa kuyatenganisha kwa kutumia regex. Ni kitu cha JSON kilichopangwa chenye shughuli za kila siku, mapendekezo ya milo, na mchanganuo wa bajeti. Kwa safari ya Goa, unaweza kupokea sehemu ya siku ya kwanza inayotenga rupia 500 kwa ajili ya kiamsha kinywa kwenye kibanda cha ufukweni, asubuhi katika Palolem, na chakula cha jioni cha vyakula vya baharini katika eneo maalum. Kila siku ina vipindi vya muda, makadirio ya gharama, na lebo kama "beach" au "food." Muundo huu ni muhimu kwa sababu programu za kisasa za kusafiri hazitaki kuchanganua aya. Zinataka vitu (objects) ambavyo zinaweza kuviunganisha na RecyclerViews au React components.

Teknolojia Zinazotumika na Kwa Nini Zinafaa

Mradi huu unatumia Spring Boot 3.5 pamoja na Spring AI. Spring AI ndicho kipengele muhimu zaidi. Inatoa muundo wa pamoja wa ChatModel ili usihitaji kuandika wateja wa HTTP (HTTP clients) wa moja kwa moja dhidi ya Azure OpenAI. Unabadilisha utegemezi (dependencies) na sifa (properties), si kodi ya huduma.

Unahitaji utegemezi minne kwenye faili lako la ujenzi (build file):

  • spring-boot-starter-web kwa ajili ya tabaka la REST.
  • spring-ai-starter-model-azure-openai ili kuunganishwa na LLM kupitia kiolesura cha Spring AI.
  • springdoc-openapi kwa ajili ya nyaraka za Swagger za kiotomatiki.
  • Lombok ili kupunguza kodi zisizo na lazima (boilerplate) katika POJOs zako za maombi na majibu.

Spring AI inakaa kati ya mantiki yako ya biashara (business logic) na mtoa huduma wa LLM. Nafasi hiyo imewekwa kwa makusudi. Inafanya madarasa yako ya @Service yawe safi na kutotegemea mtoa huduma maalum.

Uhandisi wa Prompt kwa Kutumia PromptTemplates

Kuweka prompt moja kwa moja ndani ya maandishi ya Java (Java strings) ni njia ya haraka ya kutengeneza programu isiyoweza kudhibitiwa kwa urahisi. Ikiwa timu ya bidhaa itaamua kuwa AI inapaswa kuzungumza kwa njia isiyo rasmi zaidi au kukataa makadirio ya bajeti yanayozidi kiwango fulani, hupaswi kuhitaji kuandika upya huduma yako.

Spring AI inatoa PromptTemplate. Unahifadhi muundo wa prompt kwenye faili la rasilimali (resource file) au kwenye mfululizo wa template, ukiiacha nafasi kwa ajili ya vigezo kama {destination}, {budget}, {days}, na {interests}. Wakati wa utendaji (runtime), huduma inatengeneza kitu cha Prompt na kuingiza thamani za mtumiaji.

Tenganisha ujumbe wa mfumo (system messages) na ujumbe wa mtumiaji (user messages). Tumia ujumbe wa mfumo ili kufafanua utambulisho (persona). Kwa mfano, unaiambia modeli kuwa ni mpangaji wa safari aliyebobea katika maeneo ya India, anazingatia bajeti, na ni mkali kuhusu kurudisha JSON pekee bila mabano ya markdown. Tumia ujumbe wa mtumiaji kupitisha maelezo mahususi ya safari. Mgawanyo huu husaidia unapotaka kufanya majaribio ya A/B ya utambulisho (personas) bila kubadilisha mkataba wa API.

Tabaka la Huduma: Kuzungumza na Azure OpenAI

Darasa la @Service lina kazi moja. Linatengeneza prompt, linaita modeli, linasafisha jibu, na linachanganua matokeo.

Ingiza (Inject) ChatClient au ChatModel ya Spring AI. Tengeneza PromptTemplate kwa kutumia thamani za ombi zinazoingia, kisha ita njia ya chat. Jibu linakuja kama String. Hapa ndipo mafunzo mengi yanapoishia na kodi halisi ya uzalishaji (production code) inapoanza.

LLM wakati mwingine huongeza utangulizi wa adabu. Unaweza kupata jibu linalofungua kwa "Hii hapa ni ratiba yako" na kisha kutoa JSON iliyofungwa ndani ya alama tatu za nyuma (triple backticks). Ukijaribu kuifafanua (deserialize) hiyo moja kwa moja kwa kutumia Jackson, programu yako itafeli. Ongeza njia ndogo ya msaada (helper method) inayokagua maandishi ghafi, inatafuta mabano ya kwanza ya kufungua na ya mwisho ya kufunga, na kutoa sehemu ya JSON pekee. Kisha thibitisha sehemu iliyochukuliwa. Hakikisha kuwa masharti muhimu yapo na kwamba thamani za nambari zina mantiki kabla ya kurudisha kitu hicho kwa kiongozi (controller).

Uchanganuzi huu wa kinga (defensive parsing) si wa hiari. Ni mpaka kati ya onyesho (demo) na API inayotegemeka.

Kushughulikia Makosa Kama Mfumo Uliokomaa

API za nje zinaweza kufeli. Azure OpenAI itarudisha makosa ya kikomo cha kasi (rate limit), kushindwa kwa uthibitishaji (authentication), au makosa ya muda ya 500. Ukiruhusu haya kuonekana kwa mtumiaji kama "stack traces," unapoteza uaminifu.

Tumia @RestControllerAdvice kukata (intercept) hitilafu ulimwenguni kote. Unganisha hitilafu za Spring AI, HttpClientErrorException, na RuntimeException za kawaida kwenye majibu ya hitilafu yaliyosanifiwa. Rudisha mwili wa JSON wenye ujumbe wa wazi, hali ya HTTP kama 429 kwa mipaka ya kiwango (rate limits), na maelezo ya kutosha ili mteja aweze kujaribu tena au kuweka kumbukumbu ya tatizo. Mtumiaji anapaswa kuona kitu kama "Huduma imezidiwa kwa muda. Tafadhali jaribu tena baada ya sekunde 30," badala ya skrini iliyojaa majina ya madarasa ya Java.

Usiweke Siri Moja kwa Moja (Hardcode)

Funguo yako ya Azure OpenAI API haipaswi kuwa kwenye application.properties iliyowekwa kwenye Git. Iweke nje (Externalize). Tumia vigezo vya mazingira (environment variables) vinavyorejelewa kwenye usanidi wako wa Spring, kama vile ${AZURE_OPENAI_KEY} na ${AZURE_OPENAI_ENDPOINT}. Weka faili ya ndani ya .env kwa ajili ya maendeleo, iongeze kwenye .gitignore, na uipakue kupitia "relaxed binding" ya Spring Boot. Ikiwa funguo itavuja, unaweza kuibadilisha mahali pamoja badala ya kujenga upya artifact yako.

Kufanya Majaribio Kupitia Swagger

Utegemezi (dependency) wa springdoc-openapi unaweka wazi mwisho wa Swagger UI (endpoint) wakati wa utendaji. Mara tu programu yako inapowaka, fungua /swagger-ui.html kwenye kivinjari. Unaweza kujaza mfano wa Goa moja kwa moja: mwisho (destination) kama "Goa," bajeti kama 25000, siku kama 5, mambo unayopenda kama "beaches, food." Bonyeza execute na uone ratiba ya JSON ikitokea. Hii inakuwezesha kuhakiki mabadiliko ya prompt, kuthibitisha serialization, na kushiriki mazingira ya majaribio (playground) na watengenezaji wa frontend kabla ya upande wowote kuandika unit test.

Kubadilisha Watoa Huduma Bila Kuandika Upya Code

Makampuni mapya (startups) hubadilisha watoa huduma. Labda salio la Azure litaisha, au unataka kuendesha inference dhidi ya mfano wa Ollama wa ndani ili kupunguza gharama. Kwa sababu Spring AI inaficha (abstracts) kiolesle (interface) cha ChatModel, mabadiliko hayo ni ya kiufundi tu. Badilisha utegemezi wa Maven kutoka spring-ai-starter-model-azure-openai kwenda starter nyingine, sasisha faili yako ya sifa (properties) kwa mwisho na funguo mpya, na uache darasa lako la huduma (service class) kama lilivyo. Mkataba wa API unaoonekana na programu yako ya simu unabaki vilevile.

Uwezo huo wa kubadilika (portability) unafanya usanifu huu kuwa muhimu hasa kwa bidhaa halisi. Haujaolewa na Azure. Unautumia kama injini moja iliyounganishwa kwenye mfumo safi wa Spring.

Funzo Halisi

Mfano wa AI si programu yako. Ni huduma ya nje inayotoa maandishi yasiyotabirika. Itense kwa umakini uleule utakaoutumia kwa lango la malipo (payment gateway) au API ya hali ya hewa ya upande wa tatu. Iweke nje sifa zako (credentials). Hakiki kila jibu. Safisha payload kabla ya kuichanganua (parsing). Shughulikia hitilafu ulimwenguni kote ili watumiaji wako wasione kamwe stack trace.

Acha AI ishughulikie kazi ya ubunifu ya kuunda ratiba ya Goa kwa bajeti ya rupia 25,000. Wewe shughulikia mifumo ya msingi (plumbing). Wakati hivi viwili vinapobaki vikiwa vimetenganishwa, unapata mfumo ambao unaweza kutumika kikamilifu.

Mwongozo wa awali uliokuwa na msukumo wa makala hii unaweza kupatikana hapa.

Unavutiwa kujadili Spring AI na miradi kama hiyo? Jiunge na jumuiya ya kujifunza ya GyaanSetu.