Kết nối LLM cục bộ hoặc AI tùy chỉnh với trình duyệt của bạn bằng SurfMind

SurfMind không khóa bạn vào một bộ mô hình duy nhất. Thông qua Custom Model API, bạn có thể trỏ nó đến một mô hình đang chạy trên máy của chính bạn (Ollama, LM Studio, Jan, llama.cpp, vLLM) hoặc đến hầu hết mọi nhà cung cấp AI bên ngoài có hỗ trợ OpenAI completion API — Poe, z.ai, Together, Groq, DeepSeek, AWS Bedrock, và hàng chục cái khác.

Vấn đề là: khi nó không chạy được ngay lần đầu, nguyên nhân thường chỉ là một lỗi cấu hình nhỏ. Còn thông báo lỗi bạn nhận được ("connection failed", "401", "404", "model not found") thì lại khó đoán.

Bài viết này là một bản kiểm tra nhanh để bạn tự xử lý. Hãy lướt qua danh sách và rà lại thiết lập của mình. Nếu vẫn không chạy được, hãy gửi email cho chúng tôi tại wave@surfmind.ai.

Đang tìm một nhà cung cấp cụ thể? Xem danh sách của chúng tôi: mô hình cục bộ (Ollama, LM Studio, Jan…) hoặc nhà cung cấp AI (Poe, z.ai, Together, Groq, AWS…).

Danh sách kiểm tra 60 giây

Trước hết, hãy rà soát qua những mục này. Hầu hết các vấn đề thiết lập đều quy về một trong số chúng:

1. Máy chủ có thực sự đang chạy không? Đối với mô hình cục bộ, trình chạy (Ollama, LM Studio, v.v.) phải được khởi động và đã nạp sẵn một mô hình.
2. Cổng (port) có đúng không? Ollama là 11434. LM Studio là 1234. Chúng không thay thế cho nhau được, và đây là lỗi phổ biến nhất.
3. Đường dẫn (path) có đúng không? Đường dẫn gốc của Ollama là /api/chat. Hầu như mọi thứ khác là /v1/chat/completions. Nhầm lẫn giữa chúng sẽ gây ra lỗi.
4. Bạn đã dán đầy đủ endpoint chưa, chứ không chỉ phần gốc? Trường API URL của SurfMind cần URL hoàn chỉnh kết thúc bằng /chat/completions (hoặc /api/chat đối với Ollama), chứ không chỉ https://api.provider.com/v1.
5. API key (và header của nó) có đúng không? Trình chạy cục bộ thường không cần key. Nhà cung cấp bên ngoài cần Authorization làm header và key thật của bạn làm giá trị.
6. Đối với mô hình cục bộ trong trình duyệt: CORS đã được cho phép chưa? Đây là bước bổ sung duy nhất mà các thiết lập cục bộ cần (OLLAMA_ORIGINS, hoặc "Enable CORS" trong LM Studio).

Nếu sau đó bạn vẫn mắc kẹt, hãy đọc tiếp — mỗi mục trong số này đều có một biến thể tinh vi khiến nhiều người vấp phải.

Điền gì vào từng trường

Khi bạn mở tab Custom → Add Custom Models, bạn sẽ thấy biểu mẫu "Custom Model API". Đây là chính xác những gì từng trường yêu cầu:

Hai trường mà mọi người hay nhập sai là API URL (gốc với endpoint đầy đủ) và API Key Header (header nào). Phần còn lại của hướng dẫn này sẽ đi sâu vào chúng.

Lỗi #1: đường dẫn API URL (bẫy /api/chat với /v1/chat/completions)

Đây là lỗi lớn nhất, và rất đáng để hiểu tại sao nó xảy ra.

Có hai "phương ngữ" API khác nhau trong thế giới này:

• API gốc của Ollama, dùng http://localhost:11434/api/chat.
• OpenAI completion API, dùng .../v1/chat/completions. Đây là cái mà LM Studio, vLLM, Jan, Poe, z.ai, Together, Groq — về cơ bản là mọi cái khác — đều dùng.

Vậy nên nếu bạn sao chép một hướng dẫn thiết lập được viết cho LM Studio và thử dùng đường dẫn đó với Ollama (hoặc ngược lại), bạn sẽ nhận được lỗi 404 dù máy chủ đang chạy hoàn hảo. Máy chủ vẫn hoạt động; chỉ là bạn đang gõ nhầm cửa.

Cần lưu ý: Ollama thực ra hiểu được cả hai phương ngữ. Ollama preset trong SurfMind dùng đường dẫn gốc /api/chat, đây là cách đơn giản nhất và cho bạn tính năng tự động phát hiện mô hình. Bạn chỉ cần đường dẫn /v1/chat/completions của Ollama nếu một công cụ nào đó yêu cầu cụ thể định dạng OpenAI. Với SurfMind, cứ dùng preset là được.

Lỗi #2: số cổng (port)

Mỗi trình chạy cục bộ tự chọn cổng mặc định riêng, và chúng trông đủ giống nhau để gây nhầm khi gõ:

11434 với 1234 là nhầm lẫn kinh điển — chúng dễ bị lẫn lộn khi nhìn thoáng qua, nhưng chỉ sai một chữ số là không kết nối được gì cả. Nếu bạn tự thay đổi cổng (ví dụ bạn chạy vLLM với --port 9000), hãy dùng cổng của bạn, không phải cổng mặc định.

Kiểm tra nhanh: mở cổng đó trong trình duyệt. Truy cập http://localhost:11434 sẽ hiển thị thông báo "Ollama is running" của Ollama. Nếu trang không tải được, máy chủ chưa khởi động hoặc bạn dùng sai cổng.

Lỗi #3: dán URL gốc thay vì endpoint

Tài liệu của nhà cung cấp hầu như luôn cho bạn một URL gốc — kiểu như https://api.poe.com/v1. Đó là vì các đoạn mã mẫu của họ dùng OpenAI SDK, vốn tự gắn thêm /chat/completions ở bên dưới giúp bạn.

Trường API URL của SurfMind không làm điều đó giúp bạn. Nó yêu cầu endpoint hoàn chỉnh. Vậy nên bạn phải tự thêm đường dẫn:

• URL gốc từ tài liệu: https://api.poe.com/v1
• Cái bạn dán vào SurfMind: https://api.poe.com/v1/chat/completions

Trường Models URL (dùng để tự động liệt kê các mô hình khả dụng) cũng tương tự: lấy phần gốc rồi thêm /models → https://api.poe.com/v1/models.

Hai lỗi nhỏ liên quan:

• /v1 lặp đôi. Nếu phần gốc đã kết thúc bằng /v1, đừng thêm cái nữa. .../v1/v1/chat/completions sẽ cho ra lỗi 404.
• Dấu gạch chéo thừa ở cuối. .../chat/completions/ với dấu gạch chéo cuối có thể thất bại trên một số máy chủ. Hãy bỏ nó đi.

Lỗi #4: Models URL không khớp với API URL

Models URL là tùy chọn. Đó là endpoint mà SurfMind gọi đến để lấy danh sách các mô hình mà nhà cung cấp cung cấp, để có thể hiển thị chúng trong danh sách thả xuống thay vì bắt bạn gõ tên. Nếu các mô hình của bạn không xuất hiện trong bộ chọn sau khi lưu, trường này thường là thủ phạm. Nó phải theo cùng phương ngữ với endpoint chat:

Một lỗi thường gặp là nhầm lẫn giữa chúng — dùng /api/tags với một nhà cung cấp OpenAI-compatible, hoặc /v1/models với Ollama preset (chế độ gốc). Nếu bạn đã dùng Ollama preset, trường này được điền sẵn đúng cho bạn; cứ để nguyên.

Khi nào nên để trống: một số nhà cung cấp không công khai endpoint liệt kê mô hình, hoặc chặn nó. Không sao cả — hãy để trống Models URL và tự gõ chính xác model id vào trường mô hình (xem Lỗi #7). Chat vẫn sẽ hoạt động; bạn chỉ không có danh sách thả xuống tự điền.

Lỗi #5: API Key Header (Bearer với x-api-key)

Danh sách thả xuống API Key Header quyết định cách key của bạn được gắn vào yêu cầu. Chọn sai cái và bạn sẽ nhận lỗi 401 Unauthorized ngay cả với một key hoàn toàn hợp lệ. Có ba lựa chọn:

Sau đó trường API Key chỉ nhận riêng key:

• Đừng gõ chữ Bearer — SurfMind sẽ thêm nó khi bạn chọn Authorization.
• Đừng để dấu cách thừa ở cuối (một nguyên nhân gây lỗi 401 phổ biến đến bất ngờ).
• Đối với mô hình cục bộ, hãy để trống. (LM Studio là ngoại lệ — nó cần một giá trị không rỗng nào đó; tài liệu của chính nó dùng lm-studio.)

Nếu không chắc nhà cung cấp dùng header nào: 99% nhà cung cấp OpenAI-compatible dùng Authorization. Chỉ chọn x-api-key nếu tài liệu của nhà cung cấp hiển thị rõ ràng một header x-api-key. Vẫn nhận lỗi 401? Hãy tạo lại key, kiểm tra kỹ lựa chọn header, và xác nhận không có dấu cách thừa nào.

Lỗi #6: CORS — cái bẫy chỉ có ở thiết lập cục bộ

Trình duyệt sẽ từ chối gọi đến một máy chủ cục bộ trừ khi máy chủ đó cho phép yêu cầu từ tiện ích mở rộng một cách rõ ràng. Đây là vấn đề riêng của các thiết lập cục bộ (nhà cung cấp bên ngoài thì đã cho phép sẵn).

• Ollama: khởi động nó với quyền truy cập trình duyệt được bật:

  # Mac/Linux
  OLLAMA_ORIGINS="*" ollama serve
  
  # Windows (PowerShell)
  $env:OLLAMA_ORIGINS="*"; ollama serve

  "port 11434 already in use"? Ứng dụng nền Ollama đã chạy sẵn. Hãy thoát nó trước (thanh menu trên Mac, khay hệ thống trên Windows), rồi chạy lệnh ở trên.

• LM Studio: trong tab Developer / máy chủ cục bộ, hãy bật Enable CORS trước khi khởi động máy chủ.

Thêm một điểm tinh tế: nếu localhost không kết nối được, hãy thử 127.0.0.1 thay thế (hoặc ngược lại). Trên một số hệ thống, chúng không phân giải giống nhau.

Lỗi #7: tên mô hình phải khớp chính xác

Khi đã kết nối, tên mô hình bạn chọn phải khớp chính xác với cái mà nhà cung cấp mong đợi — kể cả cách viết hoa. Nhiều người vấp phải lỗi này ở những nhà cung cấp không tự liệt kê mô hình, hoặc dùng cách đặt tên bất thường:

• Poe dùng tên bot kiểu hiển thị như Claude-Sonnet-4.6 và GPT-5.4 — sao chép chúng chính xác như cách chúng hiển thị trên Poe.
• z.ai dùng id như glm-4.6 và glm-5.
• Together AI dùng id có tiền tố không gian tên (namespace): meta-llama/Llama-3.3-70B-Instruct-Turbo, deepseek-ai/DeepSeek-V3.
• Fireworks dùng id dạng đường dẫn đầy đủ: accounts/fireworks/models/llama-v3p3-70b-instruct.

Nếu kết nối hoạt động nhưng bạn nhận được "model not found", gần như luôn là do gõ sai tên hoặc sai cách viết hoa. Khi SurfMind có thể tự liệt kê mô hình qua Models URL, hãy chọn từ danh sách thay vì gõ tay.

Tham khảo nhanh: mô hình cục bộ

Tất cả những thứ này chạy trên máy của chính bạn. Mở tab Custom của SurfMind → Add Custom Models, chọn preset phù hợp (Ollama có preset riêng; số còn lại dùng preset OpenAI-compatible chung), và đặt API Key Header thành None. Tên nhà cung cấp liên kết đến tài liệu thiết lập của từng công cụ.

Ollama

• API URL: http://localhost:11434/api/chat
• Models URL: http://localhost:11434/api/tags
• API key: không có

LM Studio

• API URL: http://localhost:1234/v1/chat/completions
• Models URL: http://localhost:1234/v1/models
• API key: bất kỳ giá trị không rỗng nào (ví dụ lm-studio)

Jan

• API URL: http://localhost:1337/v1/chat/completions
• Models URL: http://localhost:1337/v1/models
• API key: không có (hoặc key Jan của bạn)

llama.cpp

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: không có (trừ khi bạn khởi động nó với --api-key)

vLLM

• API URL: http://localhost:8000/v1/chat/completions
• Models URL: http://localhost:8000/v1/models
• API key: --api-key của bạn nếu bạn đã đặt

LocalAI

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: không có

Đừng quên bước CORS (Lỗi #6) cho bất kỳ cái nào trong số này. Riêng với Ollama, hướng dẫn đầy đủ kèm ảnh chụp màn hình nằm trong hướng dẫn Ollama của chúng tôi, và nếu bạn đang phân vân giữa hai cái đầu tiên, hãy xem Ollama với LM Studio.

Tham khảo nhanh: các nhà cung cấp AI phổ biến

Tất cả những nhà cung cấp đám mây này đều dùng API OpenAI-compatible. Hãy dùng preset OpenAI-compatible chung, đặt API Key Header thành Authorization (tất cả đều dùng Bearer token), và dán key của bạn. Tên nhà cung cấp liên kết đến tài liệu API của từng nhà cung cấp.

Poe — một key cho hàng trăm mô hình (Claude, GPT, Gemini, Llama…), được tính vào điểm đăng ký Poe của bạn. Tên mô hình là tên bot kiểu hiển thị — sao chép chúng chính xác như hiển thị trên Poe (ví dụ Claude-Sonnet-4.6, GPT-5.4). Lấy key từ poe.com → Settings → API key.

• API URL: https://api.poe.com/v1/chat/completions
• Models URL: https://api.poe.com/v1/models

CanopyWave — nhà cung cấp GPU-cloud phục vụ các mô hình mở (Kimi, DeepSeek, Llama, Qwen). Lấy key từ bảng điều khiển CanopyWave.

• API URL: https://inference.canopywave.io/v1/chat/completions
• Models URL: https://inference.canopywave.io/v1/models

z.ai (GLM) — các mô hình GLM của Zhipu (glm-4.6, glm-5). Lưu ý: z.ai cũng công bố một endpoint Coding Plan riêng (https://api.z.ai/api/coding/paas/v4) và một endpoint PaaS (https://api.z.ai/api/paas/v4) — hãy dùng endpoint OpenAI-compatible bên dưới và đừng thêm /v1 dư.

• API URL: https://api.z.ai/api/openai/v1/chat/completions
• Models URL: https://api.z.ai/api/openai/v1/models

Together AI — danh mục mô hình mở lớn. Model id thì dài (meta-llama/Llama-3.3-70B-Instruct-Turbo) — sao chép chúng chính xác từ trang mô hình của Together.

• API URL: https://api.together.xyz/v1/chat/completions
• Models URL: https://api.together.xyz/v1/models

Groq — suy luận cực nhanh. Điểm cần lưu ý: đường dẫn là /openai/v1, không phải chỉ /v1.

• API URL: https://api.groq.com/openai/v1/chat/completions
• Models URL: https://api.groq.com/openai/v1/models

DeepSeek — các mô hình hiện tại là deepseek-v4-flash và deepseek-v4-pro (các tên gọi cũ deepseek-chat / deepseek-reasoner đang được loại bỏ — hãy kiểm tra tài liệu của DeepSeek để biết bản mới nhất). Phần /v1 là tùy chọn; DeepSeek chấp nhận URL có hoặc không có nó.

• API URL: https://api.deepseek.com/v1/chat/completions
• Models URL: https://api.deepseek.com/v1/models

Mistral — mistral-large-latest, mistral-small-latest, v.v. OpenAI-compatible tiêu chuẩn.

• API URL: https://api.mistral.ai/v1/chat/completions
• Models URL: https://api.mistral.ai/v1/models

Fireworks AI — điểm cần lưu ý: đường dẫn là /inference/v1, không phải /v1. Model id trông giống accounts/fireworks/models/llama-v3p3-70b-instruct.

• API URL: https://api.fireworks.ai/inference/v1/chat/completions
• Models URL: https://api.fireworks.ai/inference/v1/models

xAI (Grok) — các mô hình Grok (grok-4, v.v.). OpenAI-compatible tiêu chuẩn.

• API URL: https://api.x.ai/v1/chat/completions
• Models URL: https://api.x.ai/v1/models

AWS Bedrock — Bedrock giờ có một endpoint OpenAI-compatible, nhưng với hai điểm cần lưu ý: host phụ thuộc vào vùng (region) (ví dụ us-west-2) và đường dẫn là /openai/v1. Bạn phải dùng một Bedrock API key (một bearer token bạn tạo trong console) — không phải access key/SigV4 thông thường của AWS. Model id trông giống openai.gpt-oss-120b-1:0.

• API URL: https://bedrock-runtime.<region>.amazonaws.com/openai/v1/chat/completions
• Models URL: để trống — nhập model id sau

Vẫn không kết nối được? Phân loại cuối cùng

Hãy rà từ trên xuống danh sách này:

1. Mở host của API URL trong trình duyệt. Máy chủ cục bộ không tải được → nó chưa chạy, hoặc sai cổng.
2. Đọc lại đường dẫn. Ollama → /api/chat. Mọi cái khác → /v1/chat/completions (hoặc đường dẫn đặc biệt của nhà cung cấp trong bảng).
3. Xác nhận bạn đã dán endpoint đầy đủ, không phải phần gốc, và không có /v1 lặp đôi hay dấu gạch chéo thừa ở cuối.
4. Lỗi 401? Đó là do key hoặc header. Header = Authorization, key không có dấu cách, không có tiền tố Bearer.
5. Lỗi 404 "model not found"? Kết nối vẫn ổn — hãy sửa tên mô hình (đúng cách viết hoa).
6. Mô hình cục bộ, trình duyệt bị chặn? Bật CORS (OLLAMA_ORIGINS="*" hoặc nút bật/tắt của LM Studio), và thử 127.0.0.1 thay cho localhost.

Trình tự đó giải quyết được phần lớn áp đảo các thiết lập.

Vẫn cần trợ giúp?

Nếu bạn đã làm qua danh sách kiểm tra mà nhà cung cấp của bạn vẫn không kết nối được, hãy gửi email cho chúng tôi tại wave@surfmind.ai kèm nhà cung cấp bạn đang thử và lỗi bạn gặp. Chúng tôi sẽ giúp bạn kết nối được.

---

Đã kết nối xong? Mở SurfMind trên trang tiếp theo bạn định đọc và để mô hình của bạn bắt tay vào việc.

Tải SurfMind →