Top Level Geotools
Liên hệ
Liên hệ

Cấu hình môi trường

Hướng dẫn cấu hình file .env cho TLGeo Agent

T
Tác giả TLGeo
Thời gian đọc 5 min read
Đăng tải 2025-01-01

Cấu hình môi trường (.env)

File .env chứa các biến môi trường cấu hình cho TLGeo Agent. File này được đọc khi khởi động server và quyết định:

  • Dùng LLM provider nào (MiniMax, OpenAI, …)
  • Model nào
  • Server chạy ở port nào

⚠️ Quan trọng: File .env chứa API key — không commit file này lên Git! File .gitignore đã được cấu hình sẵn để bỏ qua.

Tạo file .env

Bước 1: Copy từ file mẫu

cd tlgeo2qgis_agent
cp .env.example .env

Bước 2: Chỉnh sửa các giá trị

Mở file .env bằng editor (VS Code, nano, vim, …) và điền giá trị thật của bạn.

Các biến môi trường

LLM_API_KEY (Bắt buộc)

API key để xác thực với LLM provider.

Lấy API key ở đâu:

Ví dụ:

LLM_API_KEY=sk-cp-g8W7vBGUtY-XO0fTLvlp0uwYKSKq_4vPDl7is0XXyeYHlCTmEBUgUfYmkr1ZcHoC0YFfa939VJyW9lpR_GRGtIk4VMko5L3BA3PVGlS1fpB-BLmdTTe8HzA

⚠️ Bảo mật: Không share API key với ai. Không commit lên Git public.

LLM_MODEL (Bắt buộc)

Tên model AI muốn sử dụng.

Các model phổ biến:

ProviderModelGhi chú
MiniMaxMiniMax-M3Mặc định trong file mẫu
OpenAIgpt-4, gpt-4-turbo, gpt-3.5-turboGPT-4 mạnh hơn nhưng đắt hơn
Anthropicclaude-3-opus, claude-3-sonnetTODO - confirm hỗ trợ
Localllama2, mistral, …Qua Ollama hoặc tương tự

Ví dụ:

LLM_MODEL=MiniMax-M3

LLM_BASE_URL (Bắt buộc)

URL endpoint API của LLM provider.

Các URL phổ biến:

ProviderBase URL
MiniMaxhttps://api.minimax.io/v1
OpenAIhttps://api.openai.com/v1
Anthropichttps://api.anthropic.com/v1
Local Ollamahttp://localhost:11434/v1
Custom proxyhttps://your-proxy.com/v1

Ví dụ:

LLM_BASE_URL=https://api.minimax.io/v1

PORT (Tùy chọn, mặc định: 13001)

Cổng server Agent lắng nghe.

Khi nào cần đổi:

  • Port 13001 đã bị chiếm
  • Chạy nhiều instance trên cùng máy
  • Reverse proxy yêu cầu port khác

Ví dụ:

PORT=13001

Ví dụ file .env đầy đủ

Cấu hình MiniMax (mặc định)

LLM_API_KEY=sk-cp-your-actual-key-here
LLM_MODEL=MiniMax-M3
LLM_BASE_URL=https://api.minimax.io/v1
PORT=13001

Cấu hình OpenAI

LLM_API_KEY=sk-your-openai-key-here
LLM_MODEL=gpt-4
LLM_BASE_URL=https://api.openai.com/v1
PORT=13001

Cấu hình Local Ollama

LLM_API_KEY=ollama
LLM_MODEL=llama2
LLM_BASE_URL=http://localhost:11434/v1
PORT=13001

⚠️ Với local Ollama, model phải được pull sẵn: ollama pull llama2

Kiểm tra cấu hình

Sau khi tạo file .env, bạn có thể test:

1. Khởi động server

python main.py

Kết quả thành công sẽ hiển thị:

INFO:     Uvicorn running on http://0.0.0.0:13001
INFO:     Application startup complete.

Nếu có lỗi API key, server vẫn chạy nhưng câu hỏi sẽ trả về lỗi.

2. Mở Web Chat UI

Truy cập http://localhost:13001 trong trình duyệt.

3. Đặt câu hỏi thử

Liệt kê tất cả layer đang mở

Nếu Agent phản hồi đúng → cấu hình OK.

Nếu lỗi 401/403 → API key sai hoặc hết hạn.

Nếu lỗi timeout → Base URL sai hoặc firewall chặn.

Các vấn đề thường gặp

”Invalid API key”

LLM_API_KEY=sk-1234abc # ← Key này không hợp lệ

Cách xử lý:

  1. Kiểm tra lại API key (copy lại từ dashboard)
  2. Đảm bảo không có khoảng trắng thừa
  3. Một số provider cần prefix (vd: Bearer )

“Model not found”

LLM_MODEL=gpt-5 # ← Model này chưa tồn tại

Cách xử lý:

  1. Kiểm tra danh sách model của provider
  2. Thử model phổ biến: gpt-3.5-turbo, MiniMax-M3

”Connection refused”

LLM_BASE_URL=https://api.minimax.io/v1 # ← URL sai

Cách xử lý:

  1. Kiểm tra URL chính xác từ documentation của provider
  2. Test kết nối: curl https://api.minimax.io/v1/

”Port already in use”

OSError: [Errno 98] Address already in use

Cách xử lý:

  1. Đổi PORT trong .env sang giá trị khác (vd: 13002)
  2. Hoặc tắt process đang dùng port 13001: lsof -i :13001

Lưu ý về bảo mật

❌ KHÔNG nên

  • Commit file .env lên Git
  • Share API key qua email/chat
  • Hardcode API key trong code
  • Để file .env ở thư mục public web

✅ NÊN

  • Thêm .env vào .gitignore (đã có sẵn)
  • Dùng environment variables cho production
  • Rotate API key định kỳ
  • Giới hạn quyền của API key (chỉ dùng cho mục đích cụ thể)

TODO cần bạn xác nhận

  • Có biến môi trường nào khác không? (DATABASE_URL, LOG_LEVEL, …)
  • Có hỗ trợ load .env từ secret manager (Vault, AWS Secrets Manager) không?
  • Có cần config cho proxy/firewall doanh nghiệp không?

Liên kết