Persiapan Lingkungan dan Konfigurasi API Key

Menjalankan contoh di repository ini butuh tiga hal: salinan repository, dependensi dari requirements.txt, dan berkas .env berisi API key. Ketiganya dirangkum README pada bagian Quick Start (README.md:76-83¹). Halaman ini hanya membahas ketiga langkah tersebut; pembahasan peran tiap modul ada di Arsitektur Repository dan Peta Modul.

Alur setup dari clone sampai script berjalan

Diagram berikut merangkum urutan yang sama, ditambah satu syarat versi Python yang dicatat di CHANGES.md.

graph LR
  clone["git clone"] --> deps["pip install -r requirements.txt"]
  py314["Python 3.14"] --> gagal["import chromadb gagal"]
  deps --> py312["Python 3.12"]
  py312 --> env[".env di root repository"]
  env --> load["load_dotenv()"]
  load --> wajib["OPENAI_API_KEY"]
  load --> ops["SECTORS_API_KEY, GROQ_API_KEY"]
  load --> ops2["HUGGINGFACEHUB_API_TOKEN, PINECONE_API_KEY, COHERE_API_KEY, STABILITY_API_KEY"]
  wajib --> run["python 01_qna.py"]
  ops --> run
  ops2 --> run
  style py314 fill:#dc2626,color:#fff
  style gagal fill:#dc2626,color:#fff
  style env fill:#f59e0b,color:#000
  style wajib fill:#2d7d46,color:#fff
  style ops fill:#8b5cf6,color:#fff
  style ops2 fill:#8b5cf6,color:#fff
%% fig: Alur setup lingkungan dari clone sampai script berjalan
%% desc: Dependensi dipasang pada Python 3.12, load_dotenv membaca .env, lalu OPENAI_API_KEY mengalir ke script contoh; key lain hanya dipakai sebagian contoh.

Clone dan pemasangan dependensi

Langkah 1 dan 2 Quick Start adalah menyalin repository lalu menjalankan pip install -r requirements.txt. Langkah 3 mengingatkan bahwa data contoh sudah tersedia di direktori news dan boleh diganti dengan berkas sendiri (README.md:76-80²).

requirements.txt mematok versi, bukan rentang. Untuk ekosistem LangChain isinya mencakup langchain==1.2.10, langchain-classic==1.0.1, langchain-community==0.4.1, langchain-groq==1.1.2, langchain-huggingface==0.1.2, langchain-openai==1.1.10, dan langchain-text-splitters==1.1.1; beberapa baris membawa komentar pemakaian, misalnya langchain-groq untuk 15_sql.py dan 16_repl.py (requirements.txt:60-67³). Dua paket inti lain adalah openai==2.21.0 dan openai-agents==0.9.2 yang dipakai berkas 19-24 (requirements.txt:93-94⁴). Paket yang menyediakan load_dotenv(), yaitu python-dotenv==1.2.1, juga dipatok di sana (requirements.txt:118⁵).

CHANGES.md mencatat versi kunci yang dipakai saat perbaikan kompatibilitas: langchain==1.2.10, langchain-community==0.4.1, langchain-openai==1.1.10, chromadb==1.5.0, llama-index==0.14.15, dan Python 3.12 (CHANGES.md:142-148⁶).

Catatan dependensi di README masih menyebut LlamaIndex 0.6.31 dan LangChain 0.0.209 sebagai versi per 2023-06-30 (README.md:107-117⁷). Angka itu tidak lagi cocok dengan isi requirements.txt sekarang, jadi pakai berkas requirements sebagai acuan.

Mengisi berkas .env

README menyuruh membuat .env di root repository dan mengisinya dengan API key OpenAI (README.md:76-83¹). Contoh lengkapnya membagi variabel ke dalam tiga komentar: # recommended untuk OPENAI_API_KEY, # optionals but useful untuk SECTORS_API_KEY dan GROQ_API_KEY, serta # completely optional (pick and choose based on your needs) untuk HUGGINGFACEHUB_API_TOKEN, PINECONE_API_KEY, DEEPSEEK_API_KEY, COHERE_API_KEY, dan STABILITY_API_KEY (README.md:85-101⁸).

⚠️ .env sudah terdaftar pada baris pertama .gitignore (.gitignore:1-1). Jangan menghapus entri itu: berkas tersebut berisi API key dan tidak boleh ikut masuk commit.

Pola pemuatan di dalam script

Script memanggil load_dotenv() sebelum membuat client, sehingga isi .env masuk ke environment proses. 01_qna.py langsung membuat OpenAIEmbeddings() setelah panggilan itu (01_qna.py:8-9⁹). 15_sql.py memakai urutan yang sama sebelum menyiapkan database dan LLM (15_sql.py:15¹⁹). 14_streamlit.py bahkan membaca nilainya secara eksplisit lewat os.getenv("OPENAI_API_KEY") (14_streamlit.py:8-10¹⁰).

Untuk SECTORS_API_KEY, pola yang dipakai adalah membaca nilainya sekali di tingkat modul lalu memakainya sebagai header Authorization pada setiap requests.get (utils/api_client.py:5-10¹¹). Pola serupa muncul di 16_repl.py (16_repl.py:27-28¹²) dan di contoh Agent SDK 20_agents_tooluse.py (20_agents_tooluse.py:8-9¹³).

15_sql.py membuat ChatGroq dengan model_name="llama-3.3-70b-versatile" tanpa parameter api key eksplisit (15_sql.py:36-38¹⁴); nilainya diambil dari environment yang diisi lewat GROQ_API_KEY seperti tercantum pada contoh .env di README.

⚠️ 07_custom.py sengaja tidak memakai key asli: baris load_dotenv() dikomentari dan environment ditimpa dengan os.environ["OPENAI_API_KEY"] = "random" (07_custom.py:25-26²⁰). Ini berlaku untuk contoh model lokal. Jangan menyalin baris tersebut ke script lain, karena panggilan ke API OpenAI akan gagal.

Versi Python dan paket platform

CHANGES.md mencatat bahwa ChromaDB memakai pydantic.v1.BaseSettings, yang tidak lagi didukung pada Python 3.14 sehingga gagal saat import. Lingkungan yang disarankan adalah Python 3.12, dibuat lewat conda (CHANGES.md:62-72²¹).

Setelah LangChain dipecah menjadi paket terpisah, CHANGES.md mendaftar paket yang harus dipasang eksplisit: langchain-community, langchain-openai, langchain-text-splitters, chromadb, dan python-dotenv (CHANGES.md:76-90²²).

requirements.txt menonaktifkan dua paket khusus Linux dengan komentar: # triton==2.0.0 (requirements.txt:152²³) dan # uvloop==0.17.0 (requirements.txt:160²⁴). CHANGES.md mencatat keduanya dikomentari karena hanya tersedia untuk Linux (CHANGES.md:135-140²⁵). README mencantumkan pesan galat yang muncul bila triton gagal dipasang pada arsitektur lain, yaitu ERROR: Could not find a version that satisfies the requirement triton (from versions: none) dan ERROR: No matching distribution found for triton (README.md:115-117²⁶).

Setelah pip install selesai dan .env terisi, contoh boleh dijalankan dalam urutan bebas; README mencontohkan python 6_team.py (README.md:103-105²⁷). Key mana yang benar-benar dibutuhkan tiap topik dibahas di Dasar LLM dan Embedding, Vector Store: Chroma Lokal dan Pinecone, dan Model Lokal dan HuggingFace.