6 phương pháp triển khai DeepSeek Harness cục bộ

TLDR DeepSeek Harness (dsh) là môi trường chạy (runtime) tác tử mã nguồn mở của DeepSeek AI, phát hành dạng bản xem trước dành cho nhà phát triển vào khoảng 13/08/2026 theo giấy phép MIT. Nó tuân theo nguyên tắc “Mô hình + Harness = Tác tử”, với mọi khả năng (mô hình, công cụ, phiên, sandbox, vòng lặp, UI) đều được triển khai dưới dạng plugin Cordis có thể hoán đổi.

Cách nhanh nhất để chạy cục bộ là npx @deepseek-ai/dsh web (yêu cầu Node.js ^22.19 hoặc ≥24), lệnh này sẽ khởi động Giao diện Web tại http://127.0.0.1:3080. Bạn cung cấp khóa API DeepSeek (hoặc tương thích OpenAI) và một workspace. Cũng có sẵn xây dựng từ mã nguồn, ứng dụng desktop, Docker, Python SDK và tích hợp với Ollama. Để có truy cập đa mô hình cấp độ sản xuất, độ tin cậy và kiểm soát chi phí khi dùng harness, hãy định tuyến yêu cầu qua endpoint hợp nhất tương thích OpenAI của CometAPI.

Những điểm chính

• DeepSeek Harness không phải là mô hình—đó là runtime/điều phối cục bộ cho phép mô hình thao tác với tệp, shell, công cụ và phiên.
• Lệnh một dòng chính thức: npx @deepseek-ai/dsh web → mở Giao diện Web cục bộ trên cổng 3080.
• Yêu cầu Node.js nghiêm ngặt: ^22.19.0 hoặc ≥24.x.
• Hỗ trợ các mô hình chính thức của DeepSeek (deepseek-v4-flash, deepseek-v4-pro), cổng tùy chỉnh tương thích OpenAI và mô hình cục bộ qua plugin/Ollama.
• Kiến trúc hoàn toàn dựa trên plugin (kernel Cordis); các chế độ gồm Standard, Minimal, Code và Creator.
• Tốc độ phổ biến nhanh: từ hàng chục nghìn đến vượt 100k sao GitHub chỉ sau vài ngày ra mắt.
• Khuyến nghị cho người dùng nâng cao: kết hợp với CometAPI (https://www.cometapi.com/) làm nhà cung cấp tùy chỉnh để truy cập 500+ mô hình, tiết kiệm 20–40% chi phí và dùng một khóa API duy nhất.
• Luôn dùng workspace tách biệt; tác tử có thể sửa tệp và chạy lệnh.
• Trạng thái bản xem trước cho nhà phát triển đồng nghĩa có thể có thay đổi phá vỡ—hãy cố định phiên bản cho các thử nghiệm gần sản xuất.

DeepSeek Harness là gì và vì sao quan trọng vào năm 2026

DeepSeek Harness (dsh) là runtime tác tử mã nguồn mở do DeepSeek AI phát triển. Phát hành theo giấy phép MIT ở trạng thái bản xem trước, nó nhấn mạnh tính tổ hợp: mọi khả năng—bộ chuyển đổi mô hình, công cụ, kỹ năng, phiên, sandbox, lưu trữ, vòng lặp tác tử, lập lịch và UI—đều tồn tại dưới dạng plugin Cordis có thể gắn, tháo, hoán đổi hoặc tái hợp qua cấu hình. Về thực chất không có “lõi đặc quyền” nào cần vá trực tiếp.

Các nguyên tắc thiết kế chính gồm:

• Tác tử = Mô hình + Harness.
• Luồng sự kiện có thể truy vết, hỗ trợ tiếp tục, phân nhánh, tìm kiếm và phát lại.
• Nhiều chế độ runtime (bộ công cụ đầy đủ tiêu chuẩn, chế độ code/điều phối, chế độ tối giản cho benchmark, chế độ creator/thử nghiệm).
• Giao diện Web ưu tiên cục bộ cho tương tác, cùng tùy chọn headless và SDK cho tự động hóa.

Nguồn chính thức:

• GitHub: https://github.com/deepseek-ai/deepseek-harness
• Trang sản phẩm/giới thiệu: https://www.deepseek.com/harness/en/ (và bản tiếng Hoa)
• Trang hướng dẫn cài đặt và các mirror cộng đồng củng cố cùng các lệnh cốt lõi.

Lưu ý thuật ngữ quan trọng: “triển khai cục bộ” có thể mang hai nghĩa. DeepSeek Harness trong hướng dẫn này chạy cục bộ trên máy của bạn, nhưng dự án deepseek-harness tiêu chuẩn kết nối tới DeepSeek V4-Pro hoặc V4-Flash qua API. Điều đó nghĩa là harness, cấu hình, phiên, xác thực và logic client có thể cục bộ, trong khi suy luận mô hình thường được thực hiện bởi API của DeepSeek. Nếu bạn cần suy luận thật sự ngoại tuyến với trọng số mô hình trên GPU của riêng bạn, đó là kiến trúc triển khai khác.

Điều kiện tiên quyết và yêu cầu hệ thống

Trước khi cài đặt, hãy kiểm tra:

• Hệ điều hành: Windows 10+, macOS 10.15+, Linux phổ biến (x64 hoặc arm64). Python SDK có ràng buộc bổ sung (Linux x64/arm64 hoặc macOS 14+ arm64).
• Node.js: Bắt buộc cho đường dẫn Giao diện Web chính. Dải mục tiêu là ^22.19.0 || >=24.0.0. Kiểm tra với node --version. Các phiên bản lẻ nằm ngoài dải này không được hỗ trợ.
• Trình quản lý gói: npm/npx (đi kèm Node). Xây dựng từ nguồn cần pnpm (cài với npm install -g pnpm).
• Git: Cần để clone mã nguồn.
• Python (tùy chọn): 3.10+ cho Python SDK chính thức.
• Khóa API / endpoint: Khóa API DeepSeek từ platform.deepseek.com, hoặc bất kỳ endpoint tương thích OpenAI + khóa + tên mô hình.
• Phần cứng: Harness không cần GPU—suy luận mô hình diễn ra từ xa (hoặc qua nhà cung cấp cục bộ bạn cấu hình). Tài nguyên laptop thông thường là đủ cho UI Web và điều phối.
• Mạng: Cần ở lần chạy đầu để tải gói; sau đó UI có thể hoạt động chỉ với các cuộc gọi API mô hình.
• Workspace: Chuẩn bị thư mục tách biệt. Tác tử có thể đọc, ghi và thực thi lệnh trong workspace đã cấu hình—không bao giờ trỏ tới dữ liệu sản xuất hoặc cá nhân nếu không có biện pháp bảo vệ.

Nguồn cho yêu cầu: README chính thức và nhiều hướng dẫn cài đặt độc lập được đăng ngay sau khi ra mắt.

Phương pháp 1: Lệnh một dòng chính thức với npx (Khuyến nghị cho hầu hết người dùng)

Đây là đường dẫn nhanh nhất và được quảng bá chính thức.

1. Đảm bảo Node.js đáp ứng yêu cầu phiên bản.
2. Mở terminal và chạy:

Bash

npx @deepseek-ai/dsh web

1. Gói được tải về (hoặc dùng cache), khởi động cấu hình Giao diện Web và in địa chỉ lắng nghe—mặc định là http://127.0.0.1:3080.
2. Mở URL đó trong trình duyệt. Chấp nhận thông báo bản xem trước nếu có.
3. Lần đầu dùng, cấu hình nhà cung cấp mô hình (Settings → Models) bằng cách dán khóa API và chọn một mô hình như deepseek-v4-flash hoặc deepseek-v4-pro.
4. Chọn hoặc tạo thư mục workspace.
5. Bắt đầu giao tác vụ.

Để dùng cổng khác:

Bash
npx @deepseek-ai/dsh web --port 8080

Các lệnh một dòng theo nền tảng cũng có trên các trang cộng đồng (PowerShell trên Windows với winget, Homebrew trên macOS, NodeSource trên Debian/Ubuntu, v.v.).

Ưu điểm: Không để lại dấu vết cài đặt lâu dài ngoài cache npm; luôn kéo phiên bản phát hành gần đây; đơn giản nhất để bắt đầu. Nhược điểm: Phụ thuộc mạng cho gói ban đầu; kém thuận tiện hơn nếu muốn đọc sâu mã nguồn hoặc build tùy chỉnh.

Phương pháp 2: Cài đặt và chạy từ mã nguồn

Dùng khi bạn muốn đọc plugin Cordis, cố định theo commit, phát triển preset tùy chỉnh hoặc đóng góp.

Bash

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Giao diện Web tương tự sẽ xuất hiện tại cổng mặc định. Các bản build bản xem trước có thể bị phá vỡ giữa các commit, nên hãy coi đây là đường dẫn thử nghiệm.

Phương pháp 3: Ứng dụng Desktop (Không cần thiết lập Node)

Các wrapper desktop từ cộng đồng và bên thứ ba đóng gói runtime để người dùng không cần tự cài Node/pnpm:

• Client nhẹ dựa trên Tauri khởi động một runtime Node đi kèm và đồng bộ harness upstream mới nhất khi chạy. Chúng chạy trên 127.0.0.1:3080, giữ dữ liệu cục bộ và đăng ký các lệnh dsh.
• Đóng gói dựa trên Electron với phụ thuộc được cố định.

Tải bộ cài từ trang Releases tương ứng trên GitHub (tìm “deepseek-harness-desktop”). Lần chạy đầu tải các thành phần lõi (vài trăm MB). Tiện cho người dùng không chuyên kỹ thuật nhưng không phải sản phẩm chính thức của DeepSeek—hãy xem xét repository và checksum SHA.

Phương pháp 4: Triển khai Docker / Container

Có các image Docker và tệp compose từ cộng đồng để chạy Giao diện Web bên trong container, thường đi kèm kết thúc HTTPS qua nginx và hỗ trợ các cổng tương thích OpenAI tùy ý. Quy trình điển hình:

Bash

git clone <docker-repo>
cd <docker-repo>
cp .env.example .env   # set API key / public host
docker compose up -d --build

Hữu ích cho truy cập qua LAN, máy chủ, hoặc môi trường không muốn cài Node trên host. Một số thiết lập hỗ trợ settings.yaml tùy chỉnh cho nhà cung cấp không phải DeepSeek.

Phương pháp 5: Python SDK cho mục đích lập trình / không giao diện

Dành cho tác tử không giám sát hoặc tích hợp vào pipeline Python:

Bash

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk

Đặt biến môi trường:

Bash

export DEEPSEEK_API_KEY=sk-your-key-here
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: export DSH_MODEL=deepseek-v4-flash

Sau đó chạy các ví dụ đã kèm sẵn hoặc dùng lớp DeepSeekHarness trong mã của bạn với workspace và thư mục phiên tách biệt. SDK đi kèm runtime riêng và không cần Node.js hệ thống.

Phương pháp 6: Tích hợp Ollama

Ollama cung cấp trình khởi chạy tiện lợi:

Bash

ollama launch dsh
# or with a specific model
ollama launch dsh --model deepseek-v4-flash:cloud

Ollama có thể cài package nếu cần và lưu trữ thiết lập khởi chạy riêng. Khả năng tìm kiếm web và hỗ trợ công cụ phụ thuộc vào mô hình đã chọn và quyền truy cập cloud của Ollama.

Cấu hình mô hình và nhà cung cấp (bao gồm CometAPI)

Trong Giao diện Web, vào Settings → Models.

• Với DeepSeek chính thức: dán khóa từ platform.deepseek.com. Các mô hình thường dùng là deepseek-v4-flash và deepseek-v4-pro.
• Với các nhà cung cấp danh mục (Anthropic, OpenAI, v.v.): dùng luồng “Add provider”.
• Với endpoint tùy chỉnh/tự host/tổng hợp: chọn “Add a custom provider.” Cung cấp ID Nhà cung cấp cố định, base URL, giao thức (thường là openai-completions), tham chiếu biến môi trường khóa API hoặc giá trị, và ít nhất một model ID.

Khuyến nghị CometAPI (rất đáng cân nhắc cho nhiều quy trình gần sản xuất) CometAPI là nền tảng hạ tầng AI hợp nhất, cung cấp 500+ mô hình (bao gồm các biến thể DeepSeek, GPT, Claude, Gemini, Grok và nhiều mô hình khác) qua một endpoint tương thích OpenAI duy nhất: https://api.cometapi.com/v1.

Lợi ích khi dùng cùng DeepSeek Harness:

• Một khóa API thay vì quản lý nhiều thông tin xác thực nhà cung cấp.
• Giá cạnh tranh (được ghi nhận tiết kiệm 20–40% so với giá trực tiếp của nhiều nhà cung cấp).
• Độ sẵn sàng cao (mục tiêu SLA 99,9%), độ trễ trung vị thấp và thanh toán theo mức dùng.
• Dễ chuyển đổi mô hình để A/B testing hoặc tối ưu chi phí mà không cần thay đổi cấu hình harness ngoài model ID.
• Tương thích cắm là chạy: các mẫu SDK OpenAI hiện có hoạt động sau khi chỉ đổi base_url và khóa.

Trong biểu mẫu nhà cung cấp tùy chỉnh của harness:

• Base URL: https://api.cometapi.com/v1
• Protocol: openai-completions (hoặc tùy chọn tương đương được hỗ trợ)
• API key: khóa CometAPI của bạn
• Model ID: bất kỳ chuỗi mô hình nào được hỗ trợ trong danh mục mô hình của CometAPI

Kết hợp này giữ lại runtime tác tử cục bộ mạnh mẽ đồng thời mang lại khả năng truy cập đa nhà cung cấp linh hoạt, tiết kiệm chi phí. Người dùng mới thường nhận được tín dụng thử miễn phí. Tài liệu: https://apidoc.cometapi.com/.

Khóa được lưu ở chế độ chỉ-ghi (ví dụ, dưới $DSH_HOME/.credentials.yaml); UI chỉ hiển thị mô tả đã che bớt.

Khắc phục sự cố DeepSeek Harness

DEEPSEEK_API_KEY không tìm thấy

Kiểm tra:

echo $DEEPSEEK_API_KEY

Trên Windows:

echo $env:DEEPSEEK_API_KEY

Nếu trống, hãy cấu hình lại.

Lỗi 400 reasoning_content

Thường do xử lý vòng đời reasoning không đúng.

Kiểm tra ứng dụng của bạn có bảo toàn thông tin reasoning của trợ lý trong các yêu cầu nhiều lượt suy nghĩ/gọi công cụ hay không.

Đây là một trong những vấn đề cốt lõi mà harness được thiết kế để xử lý.

Lỗi độ dài ngữ cảnh

Kiểm tra:

input tokens + max_tokens

Giới hạn cứng được ghi nhận là:

1,048,576 tokens

Giảm ngữ cảnh đầu vào hoặc kích thước phần hoàn thành yêu cầu.

Lệnh gọi công cụ bị sai định dạng khi streaming

Đừng giả định các mảnh stream đến theo thứ tự công cụ.

Hợp nhất phần chênh lệch của lệnh gọi công cụ theo tool_call.index, như khuyến nghị trong hợp đồng của harness.

Yêu cầu tốn chi phí bất ngờ

Kiểm tra:

• chế độ “thinking”
• độ dài đầu ra
• tỷ lệ cache-hit
• độ ổn định tiền tố prompt
• lựa chọn mô hình
• biểu giá API hiện tại

Cải thiện đơn giản thường là chuyển tác vụ thường nhật từ Pro sang Flash.

So sánh các phương pháp cài đặt và triển khai

Dữ liệu tổng hợp từ tài liệu chính thức và các hướng dẫn sau khi ra mắt (tháng 8/2026).

Kết luận và bước tiếp theo

DeepSeek Harness mang đến một runtime tác tử được thiết kế sạch sẽ, hoàn toàn dựa trên plugin cho máy cục bộ, với gần như bằng không ma sát thông qua lệnh một dòng npx. Kết hợp định tuyến mô hình linh hoạt—đặc biệt qua nền tảng hợp nhất như CometAPI—bạn có cả sức mạnh của quy trình làm việc coding tác tử hiện đại lẫn kiểm soát thực tế về chi phí, lựa chọn mô hình và tính địa phương hóa dữ liệu.

Bắt đầu ngay với:

npx @deepseek-ai/dsh web

Cấu hình khóa DeepSeek hoặc CometAPI, trỏ tới một workspace an toàn và khám phá chế độ Standard. Sau đó thử chế độ Minimal cho benchmark, nhà cung cấp tùy chỉnh để tối ưu chi phí, hoặc Python SDK cho tự động hóa.

Để có hướng dẫn chính thức mới nhất, luôn ưu tiên repository GitHub và doc. Để có độ tin cậy đa mô hình và lợi thế về giá khi chạy harness, hãy khám phá CometAPI và tài liệu tại https://apidoc.cometapi.com/.