Gateway hỗ trợ Gemini, OpenAI và Ollama cho quiz, flashcard, hỏi đáp và đánh giá. Mỗi lần chạy chọn một provider qua AI_PROVIDER; không tự chuyển provider khi có lỗi. Prompt và kiểm tra nguồn dẫn chứng vẫn dùng chung.
Vercel là nơi chạy gateway, còn Gemini/OpenAI là provider AI. Chạy gateway local để bỏ qua Vercel:
gateway/.env.local, đặt AI_PROVIDER=gemini, thêm GEMINI_API_KEY, giữ GEMINI_MODEL=gemini-3.6-flash và origin extension thật.extension/.env.local, đặt VITE_YALA_GATEWAY_URL=http://127.0.0.1:3000, VITE_YALA_AI_TIMEOUT_MS=35000; gateway dùng AI_TIMEOUT_MS=25000.npm.cmd --prefix gateway run dev. Gateway yêu cầu key trước khi khởi động.npm.cmd --prefix extension run build, rồi reload tại chrome://extensions.API key chỉ nằm ở gateway. Model cũng được chọn ở gateway; biến VITE_YALA_GEMINI_MODEL cũ không chọn model cho luồng này.
Đổi sang OpenAI Chat Completions không cần sửa logic extension: đặt AI_PROVIDER=openai, OPENAI_BASE_URL=https://api.openai.com/v1, OPENAI_API_KEY và OPENAI_MODEL, rồi restart gateway. Adapter đã gọi /chat/completions, dùng messages, max_completion_tokens, JSON schema strict và đọc choices[0].message.content. Model phải hỗ trợ các trường này. Provider bên thứ ba chỉ hỗ trợ JSON mode hoặc max_tokens sẽ cần chỉnh adapter và test tương ứng. Model reasoning có thể cần tăng ngân sách token/timeout vì token reasoning dùng chung giới hạn completion.
Để quay lại Vercel: dùng npm run dev:vercel cho runtime local hoặc npm run deploy để deploy, khôi phục URL Vercel trong extension, build và reload. Các API route, cấu hình deploy và code Vercel vẫn được giữ nguyên.
Trong Environment Variables của project gateway:
AI_PROVIDER=gemini
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_API_KEY=<key của bạn>
GEMINI_MODEL=<model hỗ trợ Interactions API của bạn>
AI_TIMEOUT_MS=25000
AI_MAX_RETRIES=0
ALLOWED_EXTENSION_ORIGINS=chrome-extension://<extension-id>
Giữ model đang hoạt động của bạn. Nếu chưa đặt AI_PROVIDER, gateway vẫn chọn Gemini và tiếp tục đọc các biến GEMINI_* cũ. AI_TIMEOUT_MS và AI_MAX_RETRIES ưu tiên hơn biến tương ứng có tiền tố GEMINI_.
AI_PROVIDER=openai
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=<key của bạn>
OPENAI_MODEL=<model hỗ trợ Structured Outputs>
AI_TIMEOUT_MS=25000
AI_MAX_RETRIES=0
ALLOWED_EXTENSION_ORIGINS=chrome-extension://<extension-id>
Adapter dùng Chat Completions với response_format: json_schema, strict: true và max_completion_tokens. URL tương thích OpenAI tùy chỉnh phải hỗ trợ đầy đủ các trường này và định dạng phản hồi Chat Completions. Xem Structured Outputs.
URL là base URL, không thêm /interactions hoặc /chat/completions. URL cloud phải dùng HTTPS, không chứa key, username, query hoặc fragment. Gateway không đi theo redirect.
Sau khi sửa biến trên Vercel, redeploy gateway. Nếu domain gateway giữ nguyên thì extension không cần build lại. Key chỉ lưu phía gateway, không đặt trong biến VITE_*.
Vercel không thể truy cập Ollama localhost trên máy bạn. Chạy gateway local bằng Node.js >=20.12.0. Chạy ollama list để lấy tên model đã cài, bao gồm tag như qwen2.5:3b.
Tạo hoặc sửa gateway/.env.local:
AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=qwen2.5:3b
AI_TIMEOUT_MS=90000
AI_MAX_RETRIES=0
ALLOWED_EXTENSION_ORIGINS=chrome-extension://<extension-id>
PORT=3000
Model ví dụ phải có trên máy. Ollama phải đang chạy. Adapter gọi /api/chat với JSON schema và không cần key. Cấu hình Ollama chỉ chấp nhận địa chỉ loopback và bị từ chối khi chạy trên Vercel. Xem Ollama Chat API.
Chạy từ thư mục repo:
npm.cmd --prefix gateway run dev:local
Sửa extension/.env.local (không phải .env.local ở thư mục gốc):
VITE_YALA_GATEWAY_URL=http://127.0.0.1:3000
VITE_YALA_AI_TIMEOUT_MS=105000
Giữ nguyên public key extension nếu đã cấu hình. Sau đó:
npm.cmd --prefix extension run build
Reload extension trong chrome://extensions. Gateway chỉ lắng nghe 127.0.0.1. Local service RAG ở cổng 8765 vẫn là dịch vụ riêng và tiếp tục dùng như trước.
Retry-After của provider được giữ lại.GET /api/health cho biết provider/model và cấu hình hợp lệ; không xác nhận key/model đã gọi inference thành công.http://127.0.0.1:11434/api/tags nếu không kết nối được..env.local hoặc API key.Kiểm tra tự động:
npm.cmd --prefix gateway run check
npm.cmd --prefix extension test
npm.cmd --prefix extension run build
Các test adapter dùng provider giả lập để kiểm tra HTTP, schema, timeout và lỗi; không thay thế việc gọi thật với key/model của bạn.