Telusur
Bot pencarian real-time tanpa database. Setiap kali kamu bertanya, bot menelusuri web saat
itu juga, lalu menjawab dengan paragraf yang mengalir. Pencariannya berjalan di balik layar:
tidak ada daftar sumber, tidak ada tautan, tidak ada langkah yang ditampilkan.
Tidak ada vector database, tidak ada Postgres, tidak ada Redis. Server sama sekali tidak
menyimpan data. Satu-satunya yang menyimpan riwayat adalah browser kamu, di localStorage.
Cara kerjanya
Browser ──POST /api/chat {pertanyaan, riwayat}──▶ FastAPI
│
0. kalau pertanyaan menyebut tempat dan tombol
Lokasi aktif: koordinat jadi nama daerah,
lalu tempat dalam radius 2 km dicari
1. tulis ulang pertanyaan jadi query mandiri
2. Tavily: cari 5 halaman web
3. susun hasilnya jadi bahan internal untuk model
4. model menulis jawaban naratif dari bahan itu
5. rapikan keluarannya, kirim lewat SSE token demi token
│
Browser ◀──────────── jawaban mengalir sebagai paragraf ┘
Empat hal yang membuat jawabannya akurat, bukan sekadar lancar:
- Query rewriting. Pertanyaan lanjutan seperti "kalau yang kedua?" diubah dulu jadi
query pencarian yang berdiri sendiri. Tanpa langkah ini, pencariannya jadi sampah.
- Grounding ketat. System prompt melarang model menjawab di luar bahan yang dikumpulkan.
Kalau bahan tidak memuat jawabannya, model disuruh bilang informasinya belum tersedia.
- Tanggal hari ini disuntik ke prompt, supaya "terbaru" dan "minggu ini" punya acuan.
- Keluaran disaring sebelum tampil. Jawaban dibersihkan dari tautan, nama domain, sitasi,
dan penanda daftar. Yang sampai ke layar hanya paragraf.
Daftar layanan, kunci API, dan fitur
Bagian ini menjawab pertanyaan "sebenarnya bot ini memakai apa saja". Semua nama variabel di
bawah sama persis dengan yang dibaca kode, jadi bisa dipakai sebagai daftar periksa saat
mengisi .env maupun dashboard Vercel.
A. Kunci penyedia teks dan gambar
| Variabel | Layanan | Gunanya | Wajib? |
|---|
DEEPSEEK_API_KEY | Tokenomix, DeepSeek, atau gateway lain | Menulis jawaban, menulis ulang pertanyaan lanjutan, dan membaca gambar | Ya |
DEEPSEEK_BASE_URL | alamat API penyedia | Ke server mana permintaan dikirim | Tidak, bawaan https://api.deepseek.com |
DEEPSEEK_MODEL | nama model | Model yang menulis jawaban | Tidak, bawaan deepseek-chat |
VISION_MODEL | nama model | Model yang mengubah gambar jadi kata kunci | Tidak, bawaan deepseek-v4-flash-vision-exp |
Kunci gambar memakai kunci yang sama dengan teks, hanya modelnya berbeda. Jadi tombol Gambar
tidak butuh pendaftaran baru. Satu catatan: kalau penyediamu tidak melayani model vision,
tombol Gambar akan gagal, dan VISION_MODEL perlu diisi nama model yang memang ada di sana.
B. Kunci pencarian web
| Variabel | Layanan | Gunanya | Wajib? |
|---|
TAVILY_API_KEY | Tavily | Mencari lima halaman web untuk setiap pertanyaan | Ya |
Tanpa kunci ini bot tidak punya bahan untuk dijawab, jadi setiap pertanyaan akan gagal dengan
pesan kuota atau kunci.
C. Kunci suara (opsional)
| Variabel | Layanan | Gunanya | Wajib? |
|---|
STT_BASE_URL | Groq atau penyedia lain yang kompatibel OpenAI | Alamat layanan transkripsi | Tidak |
STT_API_KEY | Groq | Kunci transkripsi | Tidak |
STT_MODEL | nama model | Model transkripsi | Tidak, bawaan whisper-large-v3-turbo |
Ketiganya hanya dipakai tombol Suara dan Bicara. Kalau kosong, kedua tombol itu memberi pesan
bahwa fiturnya belum dikonfigurasi, dan sisa bot tetap jalan normal.
D. Layanan yang tidak butuh kunci sama sekali
| Layanan | Gunanya | Dipakai oleh |
|---|
| Nominatim (OpenStreetMap) | Mengubah koordinat jadi nama daerah | Tombol Lokasi |
| Photon (Komoot) | Mencari tempat dalam radius 2 km | Tombol Lokasi |
| Google Fonts | Huruf Newsreader dan JetBrains Mono | Browser, langsung dari CDN |
| Vercel | Hosting fungsi Python dan berkas statis | Produksi |
Dua layanan peta itu terbuka tanpa pendaftaran. Karena itu fitur lokasi bisa dipakai tanpa
menambah satu pun kunci.
E. Pengaturan yang bukan kunci
| Variabel | Gunanya | Bawaan |
|---|
APP_ACCESS_KEY | Kalau diisi, /api/chat, /api/vision, dan /api/transcribe wajib membawa header X-Access-Key | Kosong, artinya penjaga mati |
GEO_USER_AGENT | Identitas yang dikirim ke Nominatim, diminta aturan layanannya | AmSure/1.0 (personal search bot) |
VERCEL_GIT_COMMIT_SHA | Diisi Vercel sendiri, dibaca /api/health sebagai penanda build | Kosong di komputer sendiri |
F. Fitur dan apa yang dibutuhkannya
| Fitur | Butuh | Kalau tidak tersedia |
|---|
| Jawaban naratif dari web | DEEPSEEK_API_KEY, TAVILY_API_KEY | Bot tidak bisa menjawab |
| Riwayat tetap ada setelah refresh | localStorage di browser | Tidak ada layanan yang terlibat |
| Jawaban mengalir token demi token | SSE dari FastAPI | Jawaban tetap muncul, hanya sekaligus di akhir |
| Tanya lanjutan yang nyambung | Satu panggilan LLM tambahan | Dianggap pertanyaan baru |
| Unggah gambar | DEEPSEEK_API_KEY + model vision | Tombol Gambar gagal |
| Kamera langsung | Kunci gambar + kamera browser | Tombol Kamera menampilkan pesan |
| Unggah audio | STT_BASE_URL, STT_API_KEY, STT_MODEL | Tombol Suara menampilkan pesan |
| Bicara langsung | Kunci suara + mikrofon browser | Tombol Bicara menampilkan pesan |
| Tempat terdekat | Izin lokasi browser + Nominatim + Photon | Tombol Lokasi tidak bisa dipakai |
| Halaman terkunci | APP_ACCESS_KEY | Siapa pun yang punya tautan bisa memakai kuotamu |
G. Endpoint dan penjaganya
| Endpoint | Fungsi | Perlu kunci akses? |
|---|
GET /api/health | Status konfigurasi, tanpa membocorkan nilai kunci | Tidak |
POST /api/chat | Tanya jawab, balasan SSE | Ya |
POST /api/vision | Gambar atau bingkai kamera jadi kata kunci pencarian | Ya |
POST /api/transcribe | Audio jadi teks | Ya |
GET / dan berkas statis | Halaman antarmuka | Tidak |
GET /api/docs | Dokumentasi API otomatis dari FastAPI | Tidak |
Penjaga hanya aktif kalau APP_ACCESS_KEY diisi. Di komputer sendiri biasanya dikosongkan,
di Vercel sebaiknya diisi.
H. Apa yang dipakai per satu pertanyaan
| Jenis pertanyaan | Panggilan berbayar |
|---|
| Pertanyaan pertama | 1 pencarian Tavily + 1 panggilan model |
| Pertanyaan lanjutan | 1 pencarian Tavily + 2 panggilan model |
| Pertanyaan tempat (Lokasi aktif) | Sama seperti di atas, ditambah 2 permintaan peta gratis |
| Gambar | 1 panggilan model vision, lalu dihitung seperti pertanyaan biasa |
| Suara atau Bicara | 1 transkripsi, lalu dihitung seperti pertanyaan biasa |
Yang perlu diingat soal biaya: Tavily punya kuota gratis 1.000 pencarian per bulan, Groq punya
paket gratis untuk transkripsi, dan layanan peta tidak berbayar. Yang benar-benar menagih per
pemakaian hanya penyedia model teks.
Kesimpulannya, untuk menjalankan bot ini cukup dua kunci: satu untuk model, satu untuk
pencarian. Kunci ketiga hanya perlu kalau ingin memakai suara.
Instalasi
Ikuti berurutan. Setiap langkah punya cara memeriksa bahwa langkah itu berhasil.
Butuh: macOS atau Linux, koneksi internet, dan dua API key wajib (diambil di Langkah 4).
Kunci ketiga untuk suara sifatnya opsional.
Tidak perlu MAMP, tidak perlu Node, tidak perlu Docker.
Langkah 1 — Pastikan Python 3.10 atau lebih baru ada
python3 -V
Yang benar, keluarannya seperti ini atau lebih tinggi:
Python 3.11.6
Kalau yang muncul command not found: python3, atau versinya di bawah 3.10:
brew install python
Kalau brew juga belum ada, install Homebrew dulu dari https://brew.sh, lalu ulangi.
Langkah 2 — Masuk ke folder proyek
cd /Applications/MAMP/htdocs/test-claude-code
Perintah ls seharusnya menampilkan main.py, brain.py, requirements.txt, dan frontend.
Langkah 3 — Buat virtual environment dan pasang dependency
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Prompt terminal akan berubah jadi berawalan (.venv). Itu tandanya venv aktif.
Periksa hasilnya:
python -c "import fastapi, openai, tavily; print('dependency OK')"
Harus keluar dependency OK.
Kalau python3 -m venv gagal dengan pesan soal ensurepip, jalankan
xcode-select --install, lalu ulangi Langkah 3.
Langkah 4 — Ambil dua API key
Daftar lengkap semua kunci, termasuk yang opsional, ada di bagian Daftar layanan, kunci API,
dan fitur di atas. Di langkah ini kita ambil dua yang wajib dulu.
Bot butuh dua layanan. Keduanya punya halaman pendaftaran gratis.
4a. DeepSeek — mesin yang merangkum jawaban.
- Buka https://platform.deepseek.com
- Daftar, lalu buka menu API keys
- Klik Create new API key
- Salin kuncinya (bentuknya
sk-xxxxxxxx...)
Kunci ini hanya ditampilkan sekali. Simpan dulu di catatan sementara.
4b. Tavily — mesin pencari yang membuka halaman web.
- Buka https://app.tavily.com
- Daftar dengan Google atau email
- Kunci langsung tersedia di halaman dashboard (bentuknya
tvly-xxxxxxxx...)
Kuota gratisnya 1.000 pencarian per bulan, cukup untuk pemakaian pribadi.
Langkah 5 — Isi file .env
cp .env.example .env
Buka .env dengan editor apa pun. Ada dua pilihan, pakai salah satu.
Pilihan A — DeepSeek resmi. Ganti dua baris ini:
DEEPSEEK_API_KEY=sk-kunci-kamu-yang-asli
TAVILY_API_KEY=tvly-kunci-kamu-yang-asli
Pilihan B — gateway OpenAI-compatible, misalnya Tokenomix. Beri tanda # pada blok
Pilihan A, lalu isi blok Pilihan B seperti ini:
DEEPSEEK_API_KEY=sk-tkx-kunci-dari-dashboard
DEEPSEEK_BASE_URL=https://api.tokenomixai.com/v1
DEEPSEEK_MODEL=glm-5.1
TAVILY_API_KEY=tvly-kunci-kamu-yang-asli
Sesudah mengisi .env, uji koneksinya dulu tanpa membuka browser:
.venv/bin/python check_provider.py
Kalau berhasil, skrip itu mencetak satu balasan model. Kalau gagal dengan pesan soal
model, lihat nama yang tersedia:
.venv/bin/python check_provider.py --models
Dua hal yang paling sering salah di Pilihan B:
DEEPSEEK_BASE_URL harus berakhiran /v1. Tanpa itu, permintaan mendarat di alamat
yang salah dan dibalas 404.DEEPSEEK_MODEL harus persis sama dengan nama model di dashboard gateway. glm-5.1
adalah salah satu yang tersedia di Tokenomix, tapi gateway juga melayani model lain
seperti DeepSeek dan Kimi. Nama pastinya bisa dilihat lewat check_provider.py --models.
Simpan. Jangan tambahkan tanda kutip, jangan tambahkan spasi setelah =.
Periksa bahwa tidak ada placeholder tersisa (baris berawalan # diabaikan):
grep -cE '^[^#].*isi-di-sini' .env
Harus keluar 0. Kalau keluar angka lain, masih ada nilai contoh yang belum diganti.
Langkah 6 — Jalankan
uvicorn main:app --reload
Keluaran yang benar:
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process
Biarkan terminal ini terbuka. Server berhenti kalau kamu tekan Ctrl+C.
Langkah 7 — Buka dan uji
Buka http://127.0.0.1:8000 di browser.
Periksa dari terminal juga, di tab terminal baru:
curl -s http://127.0.0.1:8000/api/health
Jawaban yang benar:
{"ok":true,"deepseek_key":true,"tavily_key":true,"model":"deepseek-chat"}
Kalau ok bernilai false, berarti salah satu kunci di .env belum terbaca. Hentikan
server dengan Ctrl+C, perbaiki .env, jalankan ulang.
Lalu di browser, ketik pertanyaan yang jawabannya berubah tiap hari, misalnya
berapa harga bitcoin sekarang. Dalam beberapa detik jawaban mulai mengalir sebagai paragraf,
tanpa daftar sumber dan tanpa tautan.
Cara cepat: satu perintah
Kalau tidak mau mengetik Langkah 2 sampai 6 setiap kali, pakai skrip yang sudah disiapkan:
./run.sh
Skrip itu membuat venv kalau belum ada, memasang dependency kalau kurang, memeriksa .env,
lalu menyalakan server. Pada pemakaian pertama ia akan berhenti dan meminta kamu mengisi
.env dulu. Setelah itu, ./run.sh saja sudah cukup.
Kalau ./run.sh ditolak dengan permission denied:
chmod +x run.sh
./run.sh
Mau port lain karena 8000 sudah dipakai (misalnya oleh MAMP)?
PORT=8001 ./run.sh
Deploy ke Vercel
Vercel menerima main.py sebagai entrypoint FastAPI secara langsung, jadi tidak perlu folder
api/ atau konfigurasi routing tambahan. Folder frontend/ otomatis diangkat ke CDN.
1. Unggah ke GitHub. Folder ini belum berupa repo git. Jalankan berurutan:
git init -b main
git add -A
git status --short # pastikan .env TIDAK muncul di daftar ini
git commit -m "Bot pencarian tanpa database"
Lalu buat repo kosong di https://github.com/new, dan jalankan dua perintah git remote add
serta git push yang ditampilkan GitHub setelah repo dibuat. Kunci API tidak ikut terkirim
karena .env sudah tercantum di .gitignore.
2. Impor proyek di Vercel. Buka https://vercel.com/new, pilih repo tadi. Biarkan
framework preset terdeteksi otomatis; jangan diubah ke Next.js.
3. Isi environment variables di Project Settings, satu per satu:
| Nama | Nilai |
|---|
DEEPSEEK_API_KEY | kunci dari Tokenomix atau DeepSeek |
DEEPSEEK_BASE_URL | https://api.tokenomixai.com/v1 |
DEEPSEEK_MODEL | glm-5.3 atau model lain yang tersedia |
TAVILY_API_KEY | kunci Tavily |
APP_ACCESS_KEY | kalimat rahasia buatanmu sendiri |
Tiga variabel berikut opsional, tapi tanpanya tombol Suara tidak berfungsi:
| Nama | Nilai |
|---|
STT_BASE_URL | https://api.groq.com/openai/v1 |
STT_API_KEY | kunci dari penyedia speech to text |
STT_MODEL | whisper-large-v3-turbo |
VISION_MODEL juga bisa ditambahkan kalau ingin mengganti model pembaca gambar; kalau
dibiarkan kosong dipakai deepseek-v4-flash-vision-exp. Setelah menambah variabel apa pun,
lakukan redeploy supaya nilainya terbaca.
Baris terakhir itu penting. Tautan Vercel bersifat publik, sedangkan kunci LLM-mu berbayar.
Tanpa APP_ACCESS_KEY, siapa pun yang menemukan tautannya bisa memakai kuotamu.
Sebagai alternatif, Vercel punya Deployment Protection bawaan di Settings. Bedanya, cara
itu mewajibkan penonton punya akun Vercel dan login. Kunci akses lebih praktis kalau kamu
hanya ingin membagikan tautan ke beberapa orang tanpa memaksa mereka mendaftar. Keduanya bisa
dipakai bersamaan.
Kalau lebih suka terminal daripada dashboard, variabel yang sama bisa diisi lewat CLI. Membaca
nilai dari berkas mencegahnya tercatat di riwayat shell:
npx vercel env add DEEPSEEK_API_KEY production < ./secret.txt
npx vercel env add TAVILY_API_KEY production < ./secret.txt
npx vercel env add APP_ACCESS_KEY production < ./secret.txt
Satu jebakan yang perlu dihindari: npx vercel env pull <berkas> menimpa seluruh isi berkas
yang ditunjuk. Jangan arahkan ke .env milikmu, karena kunci Tokenomix dan Tavily yang sudah
bekerja akan hilang. Kalau perlu menarik variabel dari Vercel, pakai nama lain seperti
.env.vercel.
4. Deploy. vercel.json sudah menyetel region sin1 (Singapura) dan maxDuration 300
detik, yaitu batas tertinggi paket Hobby. Angka itu ditulis eksplisit supaya tidak tertimpa
pengaturan dashboard yang lebih rendah.
5. Uji. Buka https://nama-proyek.vercel.app. Halaman akan meminta kunci akses; masukkan
nilai APP_ACCESS_KEY yang tadi dibuat. Kunci tersimpan di browser, jadi hanya diminta sekali.
Untuk memeriksa dari terminal:
curl -s https://nama-proyek.vercel.app/api/health
Balasan {"ok":true,...,"access_required":true} berarti konfigurasi terbaca. Permintaan ke
/api/chat tanpa header X-Access-Key akan dijawab 401.
Permintaan pertama setelah lama menganggur bisa terasa lambat karena function bangun dari nol.
Itu normal di paket gratis.
Untuk memastikan aset statis benar-benar dilayani CDN dan bukan dari function:
curl -sSI https://nama-proyek.vercel.app/style.css | grep -iE 'x-vercel-cache|cache-control'
x-vercel-cache: HIT berarti berkas itu datang dari CDN. Kalau hasilnya kosong atau MISS,
halaman tetap berfungsi, hanya saja setiap permintaan aset ikut membangunkan function.
Membangun ulang setelah mengubah variabel
Variabel environment hanya terbaca saat build baru, jadi menambah atau mengubahnya tidak
berpengaruh sampai kamu membangun ulang. Ada tiga cara, pilih yang paling nyaman.
Lewat dashboard. Buka proyek di Vercel, tab Deployments, klik tombol ⋯ di kanan
deployment paling atas, lalu pilih Redeploy. Setelah menyimpan variabel baru, Vercel
kadang juga menampilkan tombol Redeploy langsung di halaman itu.
Lewat commit kosong. Memicu build baru tanpa mengubah kode sama sekali:
git commit --allow-empty -m "Picu deploy ulang"
git push origin main
Lewat CLI.
npx vercel --prod
Setelah build selesai, pastikan hasilnya di /api/health. Ada dua penanda yang berguna:
"commit" berisi tujuh huruf pertama commit yang sedang dipasang di produksi. Bandingkan
dengan git rev-parse --short HEAD di komputermu. Kalau sama, build terbaru sudah live."stt_ready" berubah dari false menjadi true setelah STT_BASE_URL dan STT_API_KEY
terpasang di dashboard.
Deploy lewat terminal, tanpa GitHub
Vercel CLI tidak perlu dipasang permanen; npx cukup:
npx vercel login
npx vercel link
npx vercel --prod
Perintah pertama membuka browser untuk masuk. link menghubungkan folder ini ke sebuah proyek,
--prod menerbitkannya. Isi dulu environment variable lewat dashboard atau npx vercel env add,
karena deploy tanpa kunci akan tetap berjalan tetapi setiap pertanyaan gagal.
Troubleshooting
| Yang muncul | Artinya | Perbaikan |
|---|
command not found: uvicorn | venv tidak aktif | source .venv/bin/activate, atau pakai .venv/bin/uvicorn main:app --reload |
ModuleNotFoundError: No module named 'fastapi' | Dependency tidak terpasang di interpreter yang dipakai | source .venv/bin/activate lalu pip install -r requirements.txt |
[Errno 48] Address already in use | Port 8000 sudah dipakai proses lain | uvicorn main:app --reload --port 8001 |
DEEPSEEK_API_KEY belum di-set | .env tidak ada atau kosong | Pastikan .env ada di folder yang sama dengan main.py, lalu restart server |
ok:false di /api/health | Salah satu kunci tidak terbaca | Cek nama variabel di .env harus persis DEEPSEEK_API_KEY dan TAVILY_API_KEY |
AuthenticationError atau 401 | Kunci salah atau sudah dicabut | Buat kunci baru di dashboard, ganti di .env, restart |
404 saat menjawab | DEEPSEEK_BASE_URL salah, biasanya kurang /v1 | Samakan persis dengan base URL di dashboard gateway |
| Balasan 400 soal model | DEEPSEEK_MODEL tidak dikenali gateway | Salin nama model apa adanya dari dashboard gateway |
Insufficient Balance atau 402 | Saldo akun DeepSeek belum diisi | Isi ulang di https://platform.deepseek.com/top_up. Tidak perlu restart |
Pencarian web gagal: 432 | Kuota gratis Tavily habis | Tunggu bulan berikutnya atau naikkan paket |
| Halaman terbuka tapi muncul "Server tidak merespons" | uvicorn sudah berhenti | Jalankan ulang Langkah 6 |
| Tampilan tanpa font yang benar | Google Fonts tidak terjangkau |
Untuk menghentikan server: Ctrl+C di terminal tempat uvicorn berjalan.
Struktur
.
├── main.py Endpoint HTTP dan streaming SSE
├── brain.py Inti RAG: rewrite, search, prompt, saring keluaran
├── geo.py Tempat sekitar: koordinat, jarak, OpenStreetMap
├── check_provider.py Skrip uji koneksi ke penyedia LLM
├── frontend/
│ ├── index.html
│ ├── style.css
│ └── app.js
├── tests/test_brain.py Tes untuk fungsi murni, tanpa jaringan
├── run.sh Skrip sekali-jalan
├── requirements.txt
└── .env.example
Pemisahannya disengaja. brain.py tidak tahu apa-apa soal HTTP, jadi bisa dites dan dipakai
ulang oleh antarmuka lain. main.py hanya urusan transport.
Tes
source .venv/bin/activate
pytest -q
Tes ini hanya menguji fungsi murni: penyusunan konteks, pemetaan hasil pencarian, dan
perakitan prompt. Tidak memanggil API, jadi tidak butuh kunci dan tidak memakan biaya.
Mengubah perilaku
| Ingin | Ubah di |
|---|
| Jumlah sumber per pencarian | MAX_RESULTS di brain.py |
| Panjang potongan tiap sumber | SNIPPET_LIMIT di brain.py |
| Gaya dan larangan format jawaban | SYSTEM_PROMPT di brain.py |
| Aturan pembersihan keluaran | sanitize_answer di brain.py |
| Jumlah riwayat yang dikirim ke model | MAX_HISTORY di brain.py |
| Batas riwayat di browser | MAX_STORED_TURNS di frontend/app.js |
| Warna dan tipografi | token di bagian atas frontend/style.css |
| Model bahasa | DEEPSEEK_MODEL di .env |
| Radius pencarian tempat terdekat | RADIUS_METERS di geo.py (bawaan 2000 meter) |
| Jenis tempat yang dikenali | CATEGORIES di geo.py |
Karena klien LLM memakai format API yang sama dengan OpenAI, mengganti penyedia cukup dengan
mengubah DEEPSEEK_BASE_URL dan DEEPSEEK_MODEL di .env.
Unggah gambar dan suara
Lima tombol di atas kolom tulis mempercepat pencarian tanpa mengetik. Gambar dan Suara mengisi
kolom tulis dengan teks yang masih bisa kamu sunting sebelum dikirim. Bicara langsung
menjalankan pencarian. Kamera membaca objek lalu langsung mencarikannya. Lokasi menyalakan
pembacaan posisi untuk pertanyaan tentang tempat terdekat.
Gambar. Pilih berkas, lalu model vision menuliskan satu kalimat deskripsi yang siap dipakai
sebagai kata kunci pencarian. Gambar diperkecil di browser lebih dulu, jadi foto besar pun tetap
muat di bawah batas badan permintaan Vercel. Model bawaannya deepseek-v4-flash-vision-exp dari
gateway yang sama dengan model teks, dan bisa diganti lewat VISION_MODEL.
Kamera. Tekan tombol ini untuk membuka kamera belakang secara langsung. Arahkan ke objek,
lalu tekan tombol bulat di bawah layar. Bingkai yang tertangkap dikirim ke model vision, dan
jawabannya langsung dipakai sebagai pertanyaan, jadi hasil pencariannya muncul tanpa kamu
mengetik apa pun. Tombol Tutup atau tombol Escape menghentikan kamera, dan kamera juga mati
sendiri saat tab berpindah ke latar belakang. Bingkainya diambil pada sisi terpanjang 1600 piksel
supaya tulisan kecil seperti merek atau label masih terbaca.
Model diminta menyebut jenis objek lebih dulu, lalu menulis merek atau tulisan yang benar-benar
terlihat, baru ciri yang membedakannya. Kalau tulisannya tidak terbaca, model dilarang menebak.
Kamera hanya jalan di localhost atau alamat HTTPS; kalau izinnya ditolak, muncul pesan yang
meminta kamu mengizinkannya lewat ikon di address bar.
Suara. Pilih berkas audio, lalu isinya diubah menjadi teks. Gateway yang dipakai sekarang
tidak melayani audio, jadi bagian ini butuh penyedia lain yang formatnya kompatibel dengan
OpenAI. Isi tiga variabel di .env atau di dashboard Vercel:
STT_BASE_URL=https://api.groq.com/openai/v1
STT_API_KEY=gsk-kunci-dari-groq
STT_MODEL=whisper-large-v3-turbo
Groq punya paket gratis. Selama penyedianya memakai bentuk /audio/transcriptions yang sama,
cukup ganti STT_BASE_URL dan STT_MODEL. Kalau kedua variabel itu kosong, tombol Suara
menampilkan pesan bahwa fiturnya belum dikonfigurasi, bukan gagal diam-diam.
Bicara. Tekan tombol ini, lalu ucapkan pertanyaanmu. Bot menyalakan mikrofon, menampilkan
level suara dan durasi, lalu berhenti sendiri setelah kamu diam sekitar 1,6 detik. Hasil
transkripsinya langsung dikirim sebagai pencarian, jadi jawaban mulai mengalir tanpa kamu
menekan tombol kirim. Tekan Bicara sekali lagi untuk berhenti lebih cepat, dan perekaman
otomatis berhenti di batas 60 detik.
Browser akan meminta izin mikrofon sekali. Kalau izin ditolak, muncul pesan yang meminta kamu
mengizinkannya lewat ikon di address bar. Perekaman hanya jalan di localhost atau alamat
HTTPS, jadi di produksi tidak ada masalah.
Groq tidak menyediakan transkripsi bertahap kata demi kata, jadi teks muncul setelah kamu
selesai bicara, bukan saat sedang bicara. Yang tampil selama merekam adalah level suara dan
hitungan detik, sebagai tanda mikrofon benar-benar menangkap suara.
Lokasi. Tekan tombol ini sekali, izinkan browser membaca posisi, dan tombolnya berubah jadi
hijau dengan tulisan "Lokasi aktif". Setelah itu pertanyaan seperti "ATM terdekat" atau
"warung dekat sini" dijawab dengan tempat yang benar-benar ada di sekitar posisimu, lengkap
dengan perkiraan jaraknya.
Yang terjadi di balik layar: koordinat diubah dulu menjadi nama daerah, lalu tempat dicari
dalam radius 2 km dan diurutkan menurut jarak garis lurus. Hasilnya digabung dengan pencarian
web biasa, dan model menulisnya sebagai paragraf seperti biasa. Kalau pertanyaannya bukan soal
tempat, lokasi sama sekali tidak dipakai, jadi pencarian umum tidak melambat. Kalau layanan
peta sedang tidak bisa dihubungi, jawaban tetap keluar memakai pencarian web saja.
Tidak ada API key tambahan untuk fitur ini. Kedua layanan petanya, Nominatim dan Photon,
memakai data OpenStreetMap dan terbuka tanpa pendaftaran. Yang perlu diketahui soal privasi:
koordinatmu dikirim ke layanan peta itu, bukan ke Tavily dan bukan ke model bahasa. Yang masuk
ke model hanya nama daerah dan daftar tempat beserta jaraknya. Posisi juga hanya hidup di
memori tab, tidak ditulis ke localStorage, dan hilang begitu halaman dimuat ulang atau
tombolnya dimatikan.
Browser hanya mau membagi posisi di localhost atau alamat HTTPS, jadi di produksi tidak ada
masalah. Kalau izinnya ditolak, muncul pesan yang meminta kamu mengizinkannya lewat ikon di
address bar.
Cakupan datanya bergantung pada OpenStreetMap. ATM, apotek, dan minimarket biasanya lengkap di
kota besar. Warung kecil sering belum dipetakan, jadi kalau hasilnya kosong bukan berarti di
sana tidak ada warung, hanya datanya belum ada. Untuk jawaban yang lebih rapat, layanan peta
berbayar seperti Google Places bisa dipakai dengan mengganti isi geo.py; struktur pemanggilannya
sengaja dipisah di modul itu supaya penggantian tidak menyentuh brain.py.
Batas berkas 3 MB untuk gambar maupun audio, kira-kira satu sampai dua menit rekaman. Angka itu
dipilih karena Vercel menolak badan permintaan di atas 4,5 MB, dan base64 membengkak sekitar
sepertiga.
Catatan biaya
Tavily gratis 1.000 pencarian per bulan. DeepSeek berbayar per token, dan untuk satu
pertanyaan dengan lima halaman sumber biayanya di bawah satu sen. Cek halaman harga
masing-masing penyedia untuk angka terbaru.
Kalau ingin menekan biaya, tambahkan cache di memori dengan masa berlaku beberapa menit.
Cukup satu kamus {query: hasil} di brain.py, tanpa perlu database.
Kalau mau naik versi
Beberapa arah yang wajar setelah ini, dari yang paling murah usaha:
- Ganti model. Selama API-nya kompatibel dengan format OpenAI, cukup ubah
.env.
- Tambah pencarian paralel. Untuk pertanyaan majemuk, pecah jadi dua-tiga query dan
gabungkan hasilnya sebelum masuk prompt.
- Tambah cache di memori untuk pertanyaan yang berulang.
- Ganti antarmuka.
brain.py bisa dipanggil dari CLI, bot Telegram, atau WhatsApp tanpa
diubah sama sekali.
