Hướng dẫn cấu hình chính thức để kết nối DeepSeek Harness với API B.AI

DeepSeek Harness là một ứng dụng không gian làm việc AI mã nguồn mở được chú ý, hiện đang ở giai đoạn xem trước dành cho nhà phát triển. Nó không chỉ có thể phân tích mã và tệp trong không gian làm việc cục bộ mà còn mang lại cho các nhà phát triển sự linh hoạt lớn thông qua cơ chế Provider tùy chỉnh mở. B.AI, với cơ sở hạ tầng AI tiên tiến, đã xây dựng một nền tảng dịch vụ mô hình lớn toàn diện với tính khả dụng cao và độ trễ thấp, nhằm mục đích xây dựng một mạng lưới tính toán thông minh mạnh mẽ, ổn định và linh hoạt cho các nhà phát triển và doanh nghiệp.

Hướng dẫn này sẽ hướng dẫn bạn cách khởi động DeepSeek Harness từ đầu trong môi trường Windows, macOS và Linux, và tích hợp thành công với API B.AI. Theo dõi hướng dẫn này, bạn sẽ kết nối từ không gian làm việc cục bộ đến mô hình lớn trong một chu trình gọi hoàn chỉnh, giải phóng toàn bộ tiềm năng sản xuất và đổi mới do AI điều khiển.

Chuỗi gọi cuối cùng đạt được: DeepSeek Harness → B.AI API → Mô hình do B.AI cung cấp

1. Chuẩn bị môi trường

DeepSeek Harness được khởi động thông qua npx đi kèm với Node.js. Vui lòng đảm bảo hệ thống của bạn đã cài đặt phiên bản LTS Node.js hiện tại.

Địa chỉ tải xuống chính thức: https://nodejs.org/en/download

Windows

Có thể tải xuống gói cài đặt .msi trực tiếp hoặc tìm kiếm PowerShell trong menu bắt đầu, mở nó và chạy lệnh cài đặt WinGet.

macOS

Trên trang tải xuống chính thức của Node.js, chọn macOS Installer, tải xuống tệp .pkg và hoàn thành cài đặt theo hướng dẫn. Sau khi cài đặt xong, nhấn Command + Space để mở tìm kiếm, nhập Terminal và vào terminal.
Linux

Vui lòng chọn phiên bản Linux và kiến trúc hệ thống mà bạn đang sử dụng trên trang tải xuống chính thức của Node.js, và cài đặt phiên bản LTS theo lệnh quản lý gói được cung cấp trên trang. Do các lệnh cài đặt khác nhau giữa các phiên bản như Ubuntu, Debian, Fedora, v.v., nên khuyến nghị sử dụng lệnh được tạo động trên trang chính thức để đảm bảo quá trình cài đặt diễn ra suôn sẻ.

Sau khi cài đặt xong, hãy đóng tất cả các cửa sổ terminal đang mở và mở một terminal mới (người dùng Windows hãy sử dụng PowerShell, người dùng macOS sử dụng Terminal, người dùng Linux sử dụng terminal hệ thống).

Trên cả ba hệ thống, hãy chạy cùng một nhóm lệnh kiểm tra sau:

Nếu ba lệnh đều trả về số phiên bản, điều đó có nghĩa là môi trường đã sẵn sàng.

Nếu bạn dự định xây dựng và chạy dự án từ mã nguồn GitHub, bạn sẽ cần môi trường Git. Vui lòng chạy git --version trong terminal để kiểm tra xem đã cài đặt hay chưa. Nếu chưa cài đặt, hãy thực hiện các lệnh sau tùy theo hệ điều hành của bạn:

Windows

macOS

Ubuntu hoặc Debian

Chú ý: Nếu bạn chỉ có kế hoạch sử dụng phương pháp npx để trải nghiệm nhanh và cấu hình B.AI, bạn có thể bỏ qua Git.

2. Sử dụng npx để khởi động DeepSeek Harness (đề xuất)

Đối với các nhà phát triển sử dụng và cấu hình API B.AI thông thường, khuyến nghị sử dụng npx để khởi động trực tiếp.

Chạy lệnh sau trong terminal (có thể sử dụng cho cả ba hệ thống):

Khi chạy lần đầu, hệ thống sẽ hỏi bạn có muốn tải xuống các gói phần mềm cần thiết không, hãy nhập y và nhấn Enter để xác nhận.

Nếu trong quá trình khởi động xuất hiện cảnh báo về việc từ chối phụ thuộc, đó là hiện tượng bình thường và không cần can thiệp.

Khi terminal xuất ra địa chỉ cục bộ, điều đó có nghĩa là dịch vụ Web của DeepSeek Harness đã khởi động thành công.

Giữ cửa sổ terminal mở, sau đó nhập vào thanh địa chỉ của trình duyệt:

Địa chỉ này chỉ có thể truy cập từ máy cục bộ. Nếu bạn đóng cửa sổ terminal hoặc nhấn Ctrl+C trong cửa sổ, dịch vụ cục bộ sẽ dừng lại. Nếu trình duyệt không thể mở 127.0.0.1:3080, hãy kiểm tra xem terminal có còn đang chạy hay không và xác nhận rằng terminal đã xuất ra địa chỉ dsh web ở trên. Nếu cần, hãy chạy lại lệnh khởi động.

3. Cách xây dựng từ mã nguồn (nâng cao)

Nếu bạn có kế hoạch phát triển plugin, sửa đổi mã nguồn, hoặc tham gia phát triển dự án, bạn cũng có thể lấy mã nguồn từ kho GitHub chính thức.

Kho chính thức: https://github.com/deepseek-ai/deepseek-harness

Vui lòng lưu ý rằng GitHub cung cấp mã nguồn của dự án, sau khi tải xuống bạn phải hoàn thành việc cài đặt phụ thuộc và xây dựng dự án thông qua terminal, không thể chạy trực tiếp bằng cách nhấp đúp vào tệp. Bạn có thể lấy và chạy mã nguồn theo hai cách sau:

Cách một: Tải xuống gói mã nguồn ZIP Nhấp vào nút Code màu xanh lá cây trên trang kho, chọn Download ZIP. Sau khi tải xuống và giải nén, mở terminal, sử dụng lệnh cd để vào thư mục dự án đã giải nén, lần lượt chạy các lệnh sau:

Cách hai: Sử dụng Git để sao chép Khuyến nghị chạy git --version trước để kiểm tra xem môi trường Git có tồn tại hay không. Nếu chưa cài đặt, hãy tham khảo phần "Chuẩn bị môi trường" ở trên để hoàn thành cài đặt Git cho hệ thống tương ứng. Sau khi xác nhận môi trường chính xác, hãy mở lại terminal và chạy lệnh sau:

Dù bạn sử dụng phương pháp ZIP hay Git, sau khi xây dựng và khởi động thành công, địa chỉ truy cập cũng là http://127.0.0.1:3080.

4. Cấu hình Provider tùy chỉnh B.AI

Bước một, bỏ qua cấu hình mặc định của chính thức: Khi lần đầu tiên vào DeepSeek Harness, hệ thống sẽ hiển thị cửa sổ nhập API Key của mô hình chính thức. Vui lòng nhấn "Cấu hình sau". Nếu bạn nhập Key của B.AI tại đây, hệ thống sẽ không nhận diện đúng.

Bước hai, vào trang cấu hình tùy chỉnh: Nhấp vào "Cài đặt" ở góc dưới bên trái của trang, trong menu bên trái chọn "Mô hình", nhấp vào "Thêm nhà cung cấp tùy chỉnh" ở bên phải. Chú ý: Lúc này, Provider chính thức hiển thị chấm đỏ là trạng thái bình thường, không ảnh hưởng đến các thao tác tiếp theo.

Bước ba, điền thông tin API B.AI: Sau khi mở nhà cung cấp tùy chỉnh, hãy điền theo nội dung dưới đây.

Bước bốn, lấy thư mục mô hình và hoàn thành việc tạo Provider: Sau khi điền thông tin cơ bản, hãy cuộn xuống khu vực "Thư mục mô hình". Hệ thống cung cấp hai cách để thêm: nhấp vào "Thêm mô hình" để điền ID mô hình thủ công, hoặc nhấp vào "Lấy mô hình khả dụng" ở góc trên bên phải.

Khuyến nghị hoạt động: Trước tiên hãy nhấp vào "Lấy mô hình khả dụng". Để DeepSeek Harness yêu cầu trực tiếp danh sách mô hình khả dụng của tài khoản hiện tại từ B.AI. Nếu danh sách mô hình trả về bình thường, điều đó chứng tỏ rằng B.AI API Key, https://api.b.ai/v1, giao thức openai-completions, cũng như các cấu hình như giao diện danh sách mô hình đã được kết nối thành công.

Lưu ý khi chọn và thêm mô hình:

• Trong danh sách trả về, hãy chọn mô hình DeepSeek hiện có của B.AI (ví dụ có thể thấy deepseek-v4-flash hoặc deepseek-v4-pro, xin lưu ý: các mô hình khả dụng cụ thể sẽ thay đổi theo quyền hạn tài khoản và thời gian, hãy dựa vào kết quả trả về thực tế).

• Xin đừng thay đổi ID mô hình: ID mô hình phải hoàn toàn khớp với danh sách mà B.AI thực sự trả về. Xin đừng tự ý thay đổi bất kỳ chữ hoa, chữ thường, dấu gạch nối hoặc số phiên bản nào, nếu không sẽ dễ dàng gây ra lỗi model not found trong các lần gọi sau.

Sau khi xác nhận mô hình đã được thêm chính xác, cuộn xuống dưới cùng của biểu mẫu và nhấp vào "Tạo nhà cung cấp".

Sau khi tạo thành công, trang cài đặt sẽ thêm một nhà cung cấp tùy chỉnh có tên B.AI, và bên cạnh sẽ hiển thị một chấm tròn màu xanh lá cây. Điều này có nghĩa là nhà cung cấp tùy chỉnh B.AI đã được lưu thành công và đang ở trạng thái khả dụng. Lưu ý: Lúc này nếu nhà cung cấp chính thức của DeepSeek vẫn hiển thị chấm đỏ, đó là do chưa điền DeepSeek chính thức API Key, điều này không ảnh hưởng đến việc sử dụng bình thường của giao diện B.AI tương ứng với chấm xanh.

Bước năm, xác minh tính kết nối của liên kết: Đóng cửa sổ cài đặt, quay lại giao diện chính và tạo một phiên mới. Trong trình chọn mô hình, chọn nhà cung cấp B.AI, sau đó chọn mô hình DeepSeek vừa thêm, thực hiện các bài kiểm tra sau:

• Kiểm tra đối thoại cơ bản: Trong trình chọn mô hình, chọn B.AI và mô hình tương ứng, gửi lệnh:

Quan sát xem nó có thể trả về nội dung bình thường hay không, có xuất ra theo dòng hay không, đồng thời xác nhận nhà cung cấp hiện tại là B.AI, ID mô hình cũng khớp với lựa chọn của bạn.

• Kiểm tra gọi công cụ: Gửi lệnh chỉ đọc để xác minh đường dẫn công cụ:

Lệnh đặc biệt nhấn mạnh "không thay đổi hoặc xóa bất kỳ tệp nào", nhằm mục đích xác minh một cách an toàn và nhanh chóng rằng đường dẫn gọi công cụ của Harness có thông suốt mà không làm thay đổi khu vực làm việc hiện tại.

Khi thực hiện hai bài kiểm tra trên, hãy quay lại xem cửa sổ terminal chạy DeepSeek Harness, xác nhận rằng bảng điều khiển không xuất hiện thông báo lỗi 401, 404, model not found hoặc các thông báo lỗi yêu cầu khác. Nếu terminal chạy ổn định, bạn đã hoàn thành tất cả các công việc kết nối và xác minh.

Câu hỏi thường gặp Q&A

Q1: Terminal báo không tìm thấy lệnh node, npm hoặc npx?

Điều này thường xảy ra khi Node.js chưa được cài đặt hoàn tất, hoặc đường dẫn lệnh mới cài đặt chưa được terminal hiện tại đọc. Đóng tất cả các cửa sổ terminal, mở lại và chạy lại.

Nếu vẫn không tìm thấy lệnh, hãy quay lại trang tải xuống chính thức của Node.js, xác nhận rằng bạn đã cài đặt phiên bản LTS hiện tại. Người dùng Windows cũng có thể kiểm tra Node.js trong "Các ứng dụng đã cài đặt" của hệ thống, người dùng macOS và Linux có thể chạy which node để xem đường dẫn lệnh.

Q2: Khi khởi động xuất hiện npm warn deprecated, có cần xử lý không?

Hãy ưu tiên xác nhận xem có xuất hiện địa chỉ dưới đây không:

Nếu địa chỉ đó hiển thị bình thường, điều đó có nghĩa là dịch vụ Web đã khởi động thành công. deprecated trong lần thử nghiệm này thuộc về cảnh báo về việc phụ thuộc bị bỏ, có thể tiếp tục sử dụng. Nếu terminal sau đó thoát bất thường hoặc không xuất địa chỉ cục bộ, hãy kiểm tra theo thông tin lỗi cụ thể ở cuối terminal.

Q3: Trình duyệt không mở được 127.0.0.1:3080, phải làm sao?

Hãy kiểm tra xem cửa sổ terminal chạy dsh web có còn mở hay không. Đóng terminal đó hoặc sử dụng phím tắt Ctrl+C sẽ dừng dịch vụ cục bộ.

Nếu dịch vụ đã dừng, hãy thực hiện lại lệnh khởi động:

Nếu terminal báo "cổng bị chiếm dụng": hãy kết thúc tiến trình DeepSeek Harness còn lại trước đó, sau đó thử lại.

Q4: Khi gọi mô hình gặp lỗi 401 Unauthorized, làm thế nào để kiểm tra?

Lỗi 401 thường chỉ ra rằng việc xác thực API Key không thành công. Hãy kiểm tra:

• API Key có được sao chép đầy đủ không, có khoảng trắng thừa ở đầu hoặc cuối không.

• Xác nhận rằng API Key đó đang ở trạng thái hợp lệ (không bị vô hiệu hóa) trong bảng điều khiển B.AI.

• Xác nhận rằng Key đã được điền vào đúng mục cấu hình: xin đừng điền vào "DeepSeek chính thức Provider" trong cửa sổ bật lên đầu tiên, mà phải điền vào giao diện B.AI tương ứng trong "Cài đặt → Mô hình → Thêm nhà cung cấp tùy chỉnh".

Q5: Khi gọi mô hình gặp lỗi 404 Not Found, có lỗi nào trong việc điền không?

Hãy kiểm tra xem địa chỉ API đã được điền đầy đủ chưa.

Q6: Xuất hiện thông báo model not found, làm thế nào để giải quyết?

Hãy quay lại trang chỉnh sửa nhà cung cấp tùy chỉnh B.AI, nhấp lại vào "Lấy mô hình khả dụng". Hãy đảm bảo rằng ID mô hình bạn chọn hoặc điền hoàn toàn khớp với kết quả trả về từ hệ thống, giữ nguyên tất cả chữ hoa, chữ thường, dấu gạch nối và số phiên bản. Ngoài ra, việc cập nhật quyền tài khoản hoặc điều chỉnh danh sách mô hình chính thức cũng có thể khiến mô hình cũ không khả dụng, nếu gặp lỗi, hãy dựa vào danh sách mô hình mới lấy được.

Q7: Trạng thái B.AI hiển thị chấm xanh, nhưng vẫn không thể đối thoại?

Chấm xanh chỉ đại diện cho thông tin cấu hình đã được lưu. Nếu không thể đối thoại, hãy xác nhận rằng phiên hiện tại đã chọn đúng nhà cung cấp B.AI và mô hình cụ thể tương ứng, ID mô hình chính xác và tài khoản B.AI của bạn có quyền gọi và hạn mức khả dụng cho mô hình tương ứng. Sau đó, hãy kết hợp mã lỗi cuối cùng trong terminal (như 401/404) để kiểm tra cụ thể.

Q8: Có sự khác biệt nào giữa các trang kết nối của hệ điều hành Windows, macOS và Linux không?

Môi trường chuẩn bị của ba hệ điều hành có chút khác biệt. Sau khi dsh web khởi động, tất cả các hệ thống đều truy cập http://127.0.0.1:3080 qua trình duyệt, các bước thêm nhà cung cấp B.AI, lấy mô hình và xác minh đối thoại cơ bản là tương tự nhau.

Liên kết tham khảo:

• Trang tải xuống chính thức của Node.js: https://nodejs.org/en/download

• Kho lưu trữ chính thức của DeepSeek Harness: https://github.com/deepseek-ai/deepseek-harness

• Tài liệu API B.AI: https://docs.b.ai/llmservice/api/