Kihagyás

Lokál környezet összeállítása

Mindenekelőtt

Ha már korábban összeállítottuk

Vannak lépések, amelyeket nem szükséges megcsinálni, ha már korábban megtettük (többek között az alábbit sem), illetve az is lehet, hogy valamit módosítani kell ilyen esetekben. Az ilyen információkat a ikonnal ellátott blokkokban fogjuk jelezni (mint ez).

Mindenekelőtt fontos, hogy le tudjuk klónozni a python-service repository-ját. Ehhez szükséges, hogy fel legyen telepítve a git verziókezelő, és be legyen állítva az elérés a projekt GitLab repository-jához; amennyiben ez nincs meg, kövessük a megfelelő útmutatót.

Amennyiben ez megvan, klónozzuk a python-service repót abba a mappába, ahova a backend és api repository-kat is klónoztuk:

git clone git@gitlab.com:gbsolutions/granit-bank/virtualis-asszisztens/python-service.git

Innentől kezdve feltesszük, hogy a repo mappájának gyökerében, vagy legalább egy almappájában van a terminálunk a parancsok kiadásakor.

A környezet összeállítása

A függőségek és környezetek kezelésére Pixi-t használunk. Ennek telepítési útmutatója megtalálható itt: pixi.sh/latest/installation/

Az alapértelmezett Pixi környezet a fejlesztői, ez a futtatáshoz szükséges függőségek mellett tartalmaz mindent eszközt, ami a PoC fejlesztéshez, kódminőség-ellenőrzéshez illetve teszteléshez szükséges. Ezt a pixi install vagy pixi install -e default paranccsal telepíthetjük, a Python service mappájában kiadva.

A Pixi konfigurációja a pyproject.toml fájlban található.

MacOS-en CMake hiba esetén

Előfordulhat, hogy MacOS-en bármely pixi parancs esetén egy CMake-kel kapcsolatos hibaüzenetet kapunk.

TL;DR: ez megoldható úgy, hogy hozzáadjuk a következő sorokat a shell config-unkhoz:

export SDKROOT=$(xcrun --show-sdk-path)
export CPATH=$SDKROOT/usr/include/c++/v1:$CPATH

A hiba akkor jön elő, ha az xcode programnak nem telepítettük a teljes verzióját. Ekkor egy CommandLineTools nevezetű eszköztár kerül telepítésre, ami ugyan tartalmazza a teljes C++ standard könyvtárat, de ennek elérési útja nincs rendesen bekonfigurálva. Ezt végzi el az előbbi két parancs: megkeresi, hogy hol van a C++ SDK, majd láthatóvá teszi a compiler számára.

Alternatívan a hiba úgy is megoldható, ha telepítjük a teljes xcode-ot az AppStore-ból.

Emellett fontos, hogy telepítsük a LibreOffice-t is (legalábbis a Writer komponenst), ehhez itt találhatók instrukciók a megfelelő platform kiválasztása után. Mindenképp bizonyosodjunk meg róla, hogy parancssorból elérhető a LibreOffice, és amennyiben nem, vegyük fel a mappáját a PATH környezeti változóba. Az elérhetőség ellenőrizhető a soffice --version parancs kiadásával; amennyiben ez kiírja, hogy milyen verziójú LibreOffice található a gépen, nincs további teendőnk.

Miért kell a LibreOffice?

Alapvetően a LibreOffice-ra nincs szükség, hogy a program elinduljon, sőt, a funkciók nagy része működik is enélkül hiánytalanul. Az egyetlen pont, ahol a LibreOffice jelenlétét kihasználjuk, az a dokumentum-chunk-olás. Itt a konfigurációk között oldalszámbeli korlátot szabhatunk meg, ugyanakkor DOCX fájlok esetén nem tudunk oldalszámról beszélni, csak ha megjelenítjük a dokumentumot. Erre a „megjelenítésre“ LibreOffice Writer-t alkalmazzuk; ez PDF-fé konvertálja az adott DOCX fájlt, amiből már ki tudunk nyerni oldalszámot, és hibát adni, amennyiben túl hosszú a dokumentum.

A Python service-t a pixi run start parancs kiadásával tudjuk elindítani (a projekt mappájából). Ugyanakkor ez nem generálja le az API-t; amennyiben erre is szükségünk van futtassuk előbb a pixi run generate-api parancsot.

Fontos megjegyezni, hogy ez a parancs automatikusan szinkronizálja a környezetet a pyproject.toml fájlhoz (így gyakorlatilag az install parancsot sem kell kiadnunk, ez magától lefutna). Következésképp amennyiben új függőség kerül be develop-ra, ezzel nem kell foglalkoznunk, ennek telepítése megtörténik a háttérben.

A rendszer több külső API-hoz csatlakozik, melyek eléréséhez API kulcsok szükségesek. Egyik ilyen az OpenAI API, ehhez kulcsot az itt leírt módon generálhatunk. A másik az Azure Document Intelligence szolgáltatás, melyhez API kulcsot a PA-tól szerezhetünk. Ezeket a következő környezeti változókban kell megadni a helyes működés érdekében:

  • PYTHON_SERVICE_services__openai__api_key=<a generált OpenAI api kulcs>
  • PYTHON_SERVICE_services__azure__api_key=<a kapott Azure api kulcs>
Indítás máshogy

A következő módokon is indíthatjuk a Python service-t a projekt gyökeréből:

  • Ha nincs aktiválva a Pixi shell (de akkor is működik, ha aktiválva van):
    • pixi run python main.py
    • pixi run uvicorn app:app
  • Ha aktiválva van a Pixi shell:
    • python main.py
    • uvicorn app:app
Hiba: 'NoneType' object is not callable

Ismert működés, hogy a dokumentum-chunk-olás folyamata 'NoneType' object is not callable hibát ad abban az esetben, ha nem állítjuk be az Azure API kulcsot. Így amennyiben egy ilyen hibát tapasztalunk, célszerű megvizsgálni, hogy ezt megtettük-e.

IDE integrációk

JetBrains - IntelliJ IDEA

A projekten a legfőképp JetBrains IDE-ket, azon belül is az IntelliJ-t szokás használni fejlesztésre. A Python plugin telepítése lehetővé teszi, hogy IntelliJ IDEA-ban elérjük a PyCharm teljes funkcionalitását.

További hasznos plugin-ek

A Python mellett hasznos lehet, ha telepítjük a következő plugin-eket, amennyiben IntelliJ/PyCharm IDE-t választjuk fő fejlesztői környezetnek:

  • Ruff: kódminőség ellenőrzés
  • Pyright, Python Inlay Params: type-hinting és ellenőrzés
  • LSP4IJ: Fejlett language server protocol implementáció IntelliJ-hez
  • Jupyter: notebook-ok futtatása, PoC-k készítése

Ezen eszközök beállításáról bővebb információt találunk a Kódminőség oldalon

SDK hozzáadása

Adjuk hozzá IntelliJ-hez a Pixi környezetet. Ehhez először keressük meg a Pixi által létrehozott conda fájlt, illetve a Python interpreter-t:

# Interpreter
pixi run which python

# Conda executable
pixi run 'echo $CONDA_PREFIX\\libexec\\conda.bat'

# Interpreter
pixi run which python

# Conda executable
pixi run 'echo $CONDA_PREFIX/libexec/conda'

Ezután az IDEA-ban adjuk hozzá az SDK-t a következő módon:

Navigáljunk a következő ablakra a beállításokban:

Fogaskerék → Project Structure → Platform settings/SDKs → + jel → Add Python SDK from disk... → Local

Itt állítsuk be a következőket:

  • Environment: Select existing
  • Type: Conda
  • Path to conda: A megtalált conda executable útvonal

Ezután nyomjuk meg a Reload environments gombot és válasszuk ki a default környezetet.

IntelliJ Conda környezet beállítása 2025.2-es verzión

Navigáljunk a következő ablakra a beállításokban:

Fogaskerék → Project Structure → Platform settings/SDKs → + jel → Add Python SDK → Conda environment → Existing Environment

Itt állítsuk be az előbb megkeresett elérési utakat a megfelelő helyekre, majd okézzuk le.

IntelliJ Conda környezet beállítása 2024.1-es verzión

PyCharm

PyCharm esetén nem tudjuk SDK-ként hozzáadni a környezetet, és nem is ugyanott található a Project structure menüpont, mint IntelliJ-ben. Helyette ezt a beállítások Project lapján belül találjuk meg, és interpreter-ként kell hozzáadnunk, ugyanúgy a conda executable-t és default környezetet.

Miért Conda környezet?

Az IntelliJ jelenleg nem támogatja sem natív módon, sem plugin-nal a Pixi környezeteket (emellett a JetBrains SDK limitációi miatt ilyen plugin igen nagy kihívás). Ugyanakkor a pixi-pycharm függőség segítségével a Pixi legenerál egy conda fájlt, aminek segítségével az IntelliJ Conda környezetnek látja. A Pixi PyCharm támogatásáról szóló jegy itt található.

Projekt importálása és konfigurációk

Nem kell újra importálni

Amennyiben már importáltuk a projektet modulként, nem kell újra importálni. Arra viszont ügyeljünk, hogy a modul SDK-ját átállítsuk a frissen létrehozottra.

Importáljuk IntelliJ-be a python-service projektet az itt leírt módon. Az importálási folyamat során válasszuk ki a megfelelő Python SDK-t (azaz amelyiket az előbb létrehoztuk).

Felismert Django keretrendszer

Ha az importálási folyamat során az IDE felismeri a Django keretrendszert, el kell utasítani/tiltani ezt az opciót.

Utólagos SDK beállítás

A projektre vonatkozó Python SDK-t utólag is beállíthatjuk. Ehhez navigáljunk a következő ablakra, majd a Module SDK sorban válasszuk ki a megfelelő SDK-t:

Fogaskerék → Project Structure → Modules → python-service

IntelliJ Python SDK config example

Ez után beállíthatunk néhány run config-ot, a Python service egyszerű indítása érdekében. Run config-okat a következő ablakon definiálhatunk:

Run → Edit Configurations → + jel

Most az ikonnal jelzett mezőkben néhány szokásos run config-ot mutatunk.

Indítás előtti futtatások beállítása

Ez nem egy run config, hanem egy segítség, melyet komplexebb run configok összeállítására használhatunk.

Egy run config-ot lefuttathatunk egy másik részeként, annak indulása előtt. Ezt a következő módon tudjuk megtenni az Edit configurations ablakban, megfelelő config-ot kiválasztva:

Before launch: +Add task → Run another configuration → Válasszuk ki a megfelelőt

Amennyiben nem jelenik meg automatikusan egy Before launch sor, állítsuk be a következőt:

Modify options → Add before launch task

Alkalmazás indítása

Az alkalmazás indításának run config-jában a következő környezeti változók beállítása lesz szükséges.

  • PYTHONUNBUFFERED=1
  • PYTHON_SERVICE_services__openai__api_key=<a generált OpenAI api kulcs>
  • PYTHON_SERVICE_services__azure__api_key=<a kapott Azure api kulcs>

SDK módosítása

Amennyiben nem adunk hozzá új run config-ot, hanem régit módosítunk, ügyeljünk arra, hogy be legyen állítva, hogy a modul SDK-ját (vagy legalább a megfelelő interpretert) használja a config.

Adjunk hozzá egy Python típusú run config-ot. Állítsuk be, hogy ez a python-service modulhoz tartozó SDK-t használja, és a Python service mappájában található main.py script-et futtassa az -m uvicorn app:app --reload paraméterekkel. Working directory-nak állítsuk be a Python service mappáját. A következő környezeti változók szükségesek:

IntelliJ Python run config

Függőségek változása esetén

Amennyiben változnak a függőségek, ezen config indításával mindenképp figyeljünk, hogy azokat manuálisan szinkronizáljuk a pixi install parancs kiadásával. Erre azért van szükség, mivel a Python típusú config nem pixi parancsot ad ki, hanem egyenesen a környezet Python interpreter-ét hívja meg, ezzel megkerülve a Pixi automatikus szinkronizálását.

Környezet frissítése

Erre csak akkor van szükség, ha Python típusú run config-ot csináltunk indításra, ugyanis az ekkor kikerüli a pixi parancsokat, és így a környezet sem frissül. Ennek elkerülése érdekében akár megtehetjük, hogy ezt a run config-ot hozzáadhatjuk a Python config-hoz mint indítás előtti feladat.

Adjunk hozzá egy Shell Script típusú run config-ot. A mezők beállítása legyen a következő:

  • Execute: Script text
  • Script text: pixi install
  • Working directory: a Python service mappája
API generálás

Adjunk hozzá egy Shell Script típusú run config-ot. A mezők beállítása legyen a következő:

  • Execute: Script text
  • Script text: pixi run generate-api
  • Working directory: a Python service mappája

Ezt beállíthajuk akár indítás előtti feladatnak is, ha minden futtatás előtt szinkronizálni szeretnénk az api repo állapotához, és ha nem bánjuk, hogy így az indulás 3-5 másodperccel hosszabb lesz.

Debug mód

A program debug módban való indításához kattints jobb gombbal a main.py fájlra a gyökérkönyvtárban, és válaszd a Debug ‘main’ lehetőséget.

Ha valamilyen oknál fogva ez nem működik, próbáld meg a következőt:

  • Menj a Run -> Edit Configurations... menüponthoz, és a bal oldali sávban a Python alatt válaszd ki a main-t.

  • Győződj meg róla, hogy azt a Python interpreter-t választod, amelyik már be van állítva a projektben a korábbi lépések alapján.

  • Állítsd be a Munkakönyvtárat a projekt gyökérkönyvtárára.

  • Ha a következő hibát kapod:

    TypeError: 'Task' object is not callable

    akkor tiltsd le a python.debug.asyncio.repl opciót a Help -> Find Action -> Registry menüpont alatt (releváns issue: PY-62467).

Visual Studio Code

# TBD