youtube-ai-learning-assistant

Chọn provider AI

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.

Gemini local — cấu hình đang dùng

Vercel là nơi chạy gateway, còn Gemini/OpenAI là provider AI. Chạy gateway local để bỏ qua Vercel:

  1. Trong gateway/.env.local, đặt AI_PROVIDER=gemini, thêm GEMINI_API_KEY, giữ GEMINI_MODEL=gemini-3.6-flash và origin extension thật.
  2. Trong 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.
  3. Chạy npm.cmd --prefix gateway run dev. Gateway yêu cầu key trước khi khởi động.
  4. Chạy 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.

Gemini trên Vercel

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_.

OpenAI trên Vercel

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_*.

Ollama trên máy

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.

Timeout và kiểm tra

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.