Cách chạy mọi mô hình trong DeepSeek Harness

DeepSeek Harness (dsh) đi kèm với các mô hình riêng của DeepSeek được tích hợp sẵn, nhưng bạn không bị ràng buộc với chúng. Harness coi các nhà cung cấp mô hình như một cấu hình: trỏ một khối nhà cung cấp tới bất kỳ điểm cuối tương thích với OpenAI nào, cung cấp cho nó một tham chiếu thông tin xác thực, và các phiên làm việc của tác nhân của bạn sẽ chạy trên bất kỳ mô hình nào nằm sau URL đó. Một phiên bản Ollama cục bộ, một cổng công ty, Qwen thông qua chế độ tương thích của DashScope, hoặc các nhà cung cấp danh mục lớn như Anthropic và OpenAI đều có thể kết nối vào cùng một khối.

Hướng dẫn này sẽ đi sâu vào từng khóa của khối đó, sau đó xây dựng ba công thức hoạt động: một mô hình cục bộ, một điểm cuối tương thích với OpenAI được lưu trữ, và các nhà cung cấp danh mục tích hợp sẵn. Mọi thứ được trích dẫn ở đây đều lấy từ hướng dẫn nhà cung cấp chính thức trên nhánh master, được lấy vào ngày 20 tháng 8 năm 2026. Một lưu ý trước: dsh là bản xem trước dành cho nhà phát triển và tệp README cảnh báo bằng chữ in hoa rằng sẽ có những thay đổi phá vỡ khả năng tương thích. Hãy kiểm tra tài liệu với phiên bản bạn đã cài đặt trước khi sao chép bất cứ điều gì vào môi trường sản xuất.

nút

Nếu bạn mới làm quen với harness, hãy bắt đầu với DeepSeek Harness là gì và cách nó hoạt động, sau đó quay lại đây để tìm hiểu về cách kết nối các nhà cung cấp.

Tại sao phải thay đổi mô hình trong một harness tác nhân

Một harness tác nhân là một vòng lặp: mô hình lập kế hoạch, gọi công cụ, đọc kết quả và lặp lại. Harness sở hữu vòng lặp; mô hình là một thành phần. Ba lý do bạn muốn thay đổi thành phần này:

Chi phí. Các phiên làm việc của tác nhân tiêu tốn token nhanh chóng vì mỗi kết quả công cụ đều được đưa trở lại ngữ cảnh. Định tuyến các phiên làm việc thông thường đến một mô hình rẻ hơn, hoặc đến DeepSeek V4-Flash thay vì V4-Pro, sẽ thay đổi hóa đơn của bạn mà không thay đổi quy trình làm việc. Bạn có thể giữ một mô hình tiên tiến đắt tiền được cấu hình cho các phiên cần nó.

Tính cục bộ của dữ liệu. Một số codebase không thể rời khỏi tòa nhà. Một khối nhà cung cấp trỏ đến một mô hình chạy trên phần cứng của riêng bạn có nghĩa là các lời nhắc, nội dung tệp và đầu ra công cụ không bao giờ vượt qua mạng. Cùng một harness, cùng một giao diện người dùng, không có dữ liệu ra ngoài.

Phát triển cục bộ. Khi bạn đang xây dựng plugin hoặc kiểm tra hành vi của tác nhân, bạn không muốn mỗi lần lặp lại phải tốn tín dụng API hoặc phụ thuộc vào mạng của bạn. Một mô hình cục bộ nhỏ đủ nhanh để kiểm tra vòng lặp, và bạn sẽ hoán đổi lại mô hình thực khi hành vi trở nên quan trọng.

Thiết kế này tuân theo kiến trúc của dsh: mọi thứ trong harness đều là một plugin, và bộ chuyển đổi mô hình là một trong những thành phần có thể thay thế. Các tuyến nhà cung cấp thuộc sở hữu của plugin dsh-llm-pi-ai, được ghi trong danh mục cấu hình plugin của kho lưu trữ là chứa “các tuyến nhà cung cấp mà thể hiện này sở hữu.” Đó là bộ máy. Giao diện người dùng chỉ là một khối YAML.

Khối nhà cung cấp, từng khóa một

Các nhà cung cấp tùy chỉnh nằm trong $DSH_HOME/settings.yaml, và bạn cũng có thể tạo chúng từ giao diện người dùng web dưới mục Cài đặt → Mô hình. Dưới đây là ví dụ trực tiếp từ tài liệu chính thức:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

Mỗi khóa có chức năng gì:

my-gateway là ID nhà cung cấp. Đây là một định danh vĩnh viễn, vì vậy hãy chọn một tên mà bạn có thể sử dụng lâu dài; tên hiển thị trong giao diện người dùng được đặt riêng.
apiKeyEnv đặt tên cho biến môi trường chứa khóa API của bạn. Tệp cài đặt không bao giờ chứa bí mật thực tế, mà chỉ chứa tham chiếu này. Xem thêm về nơi khóa thực tế được lưu trữ bên dưới.
api khai báo giao thức truyền tải. openai-completions là giá trị được ghi trong tài liệu cho các điểm cuối tương thích với OpenAI, đây là điều làm cho lời hứa “bất kỳ mô hình nào” hoạt động: hầu hết các gateway, môi trường chạy cục bộ và các nhà cung cấp được lưu trữ đều sử dụng giao thức này.
baseURL là gốc của điểm cuối mà harness gửi yêu cầu đến.
models liệt kê các ID mô hình có sẵn thông qua nhà cung cấp này. Mỗi mục cần ít nhất một id, phải khớp với những gì điểm cuối mong đợi trong phần thân yêu cầu.
input khai báo các phương thức đầu vào cho mỗi mô hình. Các mô hình tùy chỉnh mặc định chỉ là văn bản, vì vậy một mô hình thị giác phải khai báo rõ ràng input: [text, image] nếu không các tệp đính kèm hình ảnh sẽ không đến được. Cũng có một defaultInput ở cấp độ tuyến đường để đặt giá trị dự phòng cho mọi mô hình trong nhà cung cấp; một input ở cấp độ mô hình sẽ ghi đè lên nó.
compat chứa các công tắc tương thích cho các điểm cuối lệch khỏi hành vi chuẩn của OpenAI. Tài liệu đề cập đến hai: supportsDeveloperRole: false cho các backend từ chối vai trò developer, và maxTokensField: max_tokens cho các backend muốn tên trường giới hạn đầu ra cũ hơn. Compat có thể được đặt ở cấp độ tuyến đường hoặc cho mỗi mô hình.

Một tiện ích đáng biết: khi bạn thêm một nhà cung cấp tùy chỉnh thông qua giao diện người dùng web, tùy chọn “Fetch available models” (Tìm nạp các mô hình có sẵn) sẽ truy vấn tuyến GET /models tương thích với OpenAI của điểm cuối và điền danh sách mô hình cho bạn. Nếu điểm cuối của bạn triển khai tuyến đó, bạn sẽ không cần phải nhập thủ công.

Nơi khóa API thực tế được lưu trữ

Các bí mật được lưu trữ chỉ ghi trong $DSH_HOME/.credentials.yaml. Sau khi bạn lưu một khóa thông qua giao diện người dùng, dsh chỉ trả về một mô tả đã được biên tập; giá trị thực tế không bao giờ được hiển thị lại. settings.yaml chứa các tham chiếu (tên apiKeyEnv, mô tả thông tin xác thực), không bao giờ chứa chính các khóa. Sự phân tách đó có nghĩa là bạn có thể commit hoặc chia sẻ tệp cài đặt mà không làm rò rỉ bất cứ điều gì, và xoay vòng khóa mà không cần chạm vào cấu hình nhà cung cấp.

Công thức 1: chạy một mô hình cục bộ thông qua Ollama

Ollama phơi bày một API tương thích với OpenAI tại http://localhost:11434/v1, mà Ollama ghi trong hướng dẫn tương thích OpenAI của riêng nó. Vì dsh sử dụng giao thức openai-completions với bất kỳ URL cơ sở nào, việc kết nối rất đơn giản.

[XÁC MINH: tài liệu dsh không hiển thị ví dụ cụ thể về Ollama; công thức này áp dụng schema nhà cung cấp tùy chỉnh được ghi trong tài liệu vào điểm cuối tương thích với OpenAI được ghi trong tài liệu của Ollama. Hãy kiểm tra trên bản cài đặt của bạn trước khi phát hành nội bộ.]

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3

Lưu ý về phần này:

Ollama không yêu cầu khóa API cục bộ, nhưng schema mong đợi một tham chiếu thông tin xác thực, vì vậy hãy đặt một giá trị giả: export OLLAMA_API_KEY=ollama. Ollama sẽ bỏ qua bất cứ thứ gì bạn gửi.
id của mô hình phải khớp với tag mà Ollama cung cấp. Chạy ollama list và sao chép chính xác tên, bao gồm cả tag.
Hãy kéo mô hình trước (ollama pull gpt-oss:20b) và xác nhận máy chủ phản hồi trước khi kết nối nó vào dsh. Chúng tôi đã đề cập đến thiết lập cục bộ hoàn chỉnh trong cách chạy GPT-OSS bằng Ollama, và cùng một mẫu này hoạt động cho các mô hình mã nguồn mở khác như Kimi K3 nếu phần cứng của bạn đáp ứng được.

Một kiểm tra nhanh chóng sẽ giúp bạn tránh một phiên làm việc của tác nhân gây nhầm lẫn: truy cập http://localhost:11434/v1/models trong Apidog trước khi chạm vào cấu hình dsh. Nếu yêu cầu đó trả về danh sách mô hình của bạn, URL cơ sở là đúng, máy chủ đang hoạt động, và chức năng “Fetch available models” trong giao diện người dùng dsh cũng sẽ hoạt động. Nếu không, không có cấu hình harness nào có thể khắc phục được.

Quản lý kỳ vọng: các harness tác nhân rất phụ thuộc vào việc gọi công cụ và ngữ cảnh dài. Các mô hình cục bộ nhỏ xử lý vòng lặp để thử nghiệm, nhưng chúng sẽ lập kế hoạch kém hơn và bỏ qua các lệnh gọi công cụ thường xuyên hơn so với các mô hình tiên tiến mà harness được xây dựng xung quanh. Điều đó ổn cho việc phát triển plugin; nhưng sẽ gây khó chịu cho công việc thực tế.

Công thức 2: một điểm cuối tương thích với OpenAI được lưu trữ (Qwen qua DashScope)

Đối với một ví dụ được lưu trữ, hãy chọn một nhà cung cấp ghi rõ khả năng tương thích với OpenAI của họ thay vì một nhà cung cấp mà bạn cho rằng có. Alibaba Cloud Model Studio (DashScope) làm điều đó: trang tương thích OpenAI của họ ghi rõ một điểm cuối /compatible-mode/v1 cho các mô hình Qwen, với các tên miền dành riêng cho khu vực, không gian làm việc (đối với Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) và xác thực thông qua biến môi trường DASHSCOPE_API_KEY.

Ánh xạ vào schema dsh:

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max

Thay thế {WorkspaceId} bằng tên miền không gian làm việc thực tế của bạn từ bảng điều khiển Model Studio, và kiểm tra danh sách mô hình của nhà cung cấp để biết các ID hiện tại; chúng tôi duy trì một bản tóm tắt về cấp độ hàng đầu trong hướng dẫn API Qwen 3.8 của chúng tôi. Mẫu này cũng áp dụng cho bất kỳ nhà cung cấp nào có khả năng tương thích OpenAI được ghi trong tài liệu: API Kimi của Moonshot, OpenRouter, một triển khai vLLM, hoặc gateway nội bộ của công ty bạn. Các phần duy nhất thay đổi là baseURL, tên biến môi trường và các ID mô hình. Nếu bạn đã cấu hình các mô hình mã nguồn mở trong Codex, điều này sẽ quen thuộc; khối YAML của dsh đóng vai trò tương tự như cấu hình model_providers của Codex.

Hai điểm cụ thể của điểm cuối được lưu trữ:

Nếu điểm cuối của nhà cung cấp từ chối các yêu cầu với các lỗi kỳ lạ về vai trò hoặc trường token, đó là lý do tồn tại các công tắc compat. Hãy thử supportsDeveloperRole: false trước; các triển khai tương thích OpenAI cũ hơn không có vai trò developer.
Các mô hình thị giác phải khai báo input: [text, image] một cách rõ ràng, ngay cả khi mô hình được lưu trữ hỗ trợ hình ảnh. dsh giả định các mô hình tùy chỉnh chỉ là văn bản trừ khi được chỉ định khác.

Công thức 3: các nhà cung cấp danh mục tích hợp sẵn

Bạn không cần một khối tùy chỉnh cho các đám mây chính thống. dsh cung cấp các nhà cung cấp danh mục cho DeepSeek, Anthropic và OpenAI, nơi việc thiết lập chủ yếu là “dán khóa API”. Các mục danh mục đặc biệt có luồng xác thực riêng: Bedrock sử dụng thông tin xác thực AWS, Vertex yêu cầu một dự án ADC, Azure cần phiên bản API của nó, và Codex xác thực qua OAuth.

Các nhà cung cấp danh mục là con đường ít ma sát nhất khi bạn chỉ muốn Claude hoặc GPT đứng sau harness, và đó là cách hầu hết mọi người sẽ chạy DeepSeek V4-Pro, API ra mắt vào tháng 8 năm 2026 đã đến cùng với bản thân harness (chi tiết tại api-docs.deepseek.com). Các nhà cung cấp tùy chỉnh dành cho mọi thứ mà danh mục không bao gồm: môi trường chạy cục bộ, gateway, nhà cung cấp khu vực và các bộ tổng hợp tương thích với OpenAI.

Chọn mô hình và những gì các phiên ghi nhớ

Việc thêm một nhà cung cấp làm cho các mô hình của nó có sẵn; việc chọn một mô hình trong Cài đặt → Mô hình làm cho nó trở thành mặc định cho các phiên mới. Hai hành vi từ tài liệu đáng ghi nhớ:

Các phiên hiện có giữ mô hình mà chúng đã được bắt đầu. Các phiên ghi lại mô hình ban đầu của chúng, vì vậy việc thay đổi mặc định giữa chừng dự án không âm thầm ghi lại lịch sử hoặc thay đổi những gì một phiên đang hoạt động sử dụng.
Nếu bạn xóa nhà cung cấp sở hữu mặc định hiện tại, trình soạn thảo sẽ chặn đầu vào cho đến khi bạn chọn một mô hình mới. Harness sẽ báo lỗi rõ ràng thay vì đoán.

Việc ghim phiên đó quan trọng đối với khả năng tái tạo: khi bạn so sánh dsh với các harness khác (chúng tôi đã làm điều đó trong DeepSeek Harness so với Claude Code), bạn có thể tin tưởng rằng bản ghi của một phiên phản ánh một mô hình, chứ không phải một sự thay đổi giữa chừng.

Khắc phục sự cố thường gặp

baseURL sai hoặc không thể truy cập. Lỗi phổ biến nhất là lỗi ít kỳ lạ nhất. Xác nhận rằng URL kết thúc ở nơi giao thức mong đợi (thường là /v1 cho các điểm cuối tương thích với OpenAI, /compatible-mode/v1 cho DashScope) và một yêu cầu GET {baseURL}/models đơn giản thành công bên ngoài harness. Đây là điểm kiểm tra mà Tải xuống Apidog sẽ tự trả tiền trong năm phút: gửi yêu cầu với cùng tiêu đề (Authorization: Bearer $KEY) mà harness sẽ gửi, và đọc mã trạng thái và phần thân thực tế thay vì một lỗi harness được bao bọc. Nếu bạn đang phát triển ngoại tuyến hoặc nhà cung cấp không ổn định, hãy tạo mock các phản hồi /models và /chat/completions của nhà cung cấp trong Apidog và trỏ baseURL đến mock khi bạn xây dựng.

Biến môi trường bị thiếu hoặc trống. apiKeyEnv đặt tên cho một biến; nó không tạo ra một biến. Nếu biến không được đặt trong môi trường mà dsh thực sự chạy, các yêu cầu sẽ được gửi đi mà không được xác thực và trả về lỗi 401. Hãy nhớ rằng một tiến trình được khởi chạy từ GUI hoặc trình quản lý dịch vụ có thể không kế thừa cấu hình shell của bạn. Hãy echo $GATEWAY_API_KEY trong cùng ngữ cảnh khởi chạy dsh web, chứ không chỉ trong một terminal ngẫu nhiên.

Không khớp phương thức đầu vào. Bạn đính kèm một hình ảnh, và mô hình không bao giờ thấy nó, hoặc yêu cầu bị lỗi. Các mô hình tùy chỉnh mặc định chỉ là văn bản. Thêm input: [text, image] vào mục mô hình, hoặc đặt defaultInput ở cấp độ tuyến đường nếu mọi mô hình trên nhà cung cấp đều xử lý hình ảnh.

Những bất thường của giao thức. Các lỗi đề cập đến vai trò không được hỗ trợ hoặc tham số token bị từ chối chỉ ra các công tắc tương thích: supportsDeveloperRole: false và maxTokensField: max_tokens là hai công tắc được ghi trong tài liệu.

Mọi thứ đều hoạt động vào hôm qua. Bản xem trước dành cho nhà phát triển. Hãy ghim phiên bản bạn triển khai, đọc ghi chú phát hành trước khi nâng cấp, và dự kiến schema cài đặt sẽ thay đổi. Kho lưu trữ deepseek-harness là nguồn thông tin đáng tin cậy, không phải bất kỳ bài đăng blog nào, bao gồm cả bài này.

Một lưu ý tích hợp nữa: các nhà cung cấp mô hình chỉ là một nửa câu chuyện tùy chỉnh. Nửa còn lại là các công cụ mà tác nhân có thể gọi, và bạn có thể kết nối trực tiếp các quy trình làm việc API của mình; chúng tôi đề cập điều đó trong sử dụng Apidog CLI bên trong DeepSeek Harness.

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

DeepSeek Harness có hỗ trợ Ollama chính thức không?

Tài liệu nhà cung cấp chính thức không đề cập đến Ollama bằng tên. Điều mà nó hỗ trợ là bất kỳ điểm cuối nào sử dụng giao thức openai-completions, và Ollama ghi trong tài liệu một API tương thích với OpenAI tại http://localhost:11434/v1. Công thức trên kết hợp hai nửa được ghi trong tài liệu; hãy kiểm tra nó trên bản cài đặt của bạn, vì dsh là bản xem trước dành cho nhà phát triển và schema có thể thay đổi giữa các bản phát hành.

dsh lưu trữ khóa API của tôi ở đâu?

Trong $DSH_HOME/.credentials.yaml, chỉ ghi. Giao diện người dùng hiển thị một mô tả đã được biên tập sau khi lưu, và settings.yaml chỉ chứa các tham chiếu như tên apiKeyEnv. Bạn sẽ không bao giờ có một khóa văn bản thuần túy bên trong cấu hình nhà cung cấp của mình.

Tôi có thể chạy các mô hình khác nhau cho các phiên khác nhau không?

Có. Việc chọn một mô hình chỉ đặt mặc định cho các phiên mới; mọi phiên hiện có giữ mô hình mà chúng đã bắt đầu. Vì vậy, bạn có thể chạy một mô hình rẻ tiền như DeepSeek V4-Flash cho các phiên thông thường, chuyển mặc định sang một mô hình nặng hơn cho một vấn đề khó, và các phiên trước đó của bạn vẫn không bị ảnh hưởng.

Điểm cuối tùy chỉnh của tôi trả về lỗi mà cùng một yêu cầu không tạo ra trong curl. Bây giờ phải làm gì?

So sánh các payload chính xác. Harness có thể gửi vai trò developer hoặc một trường giới hạn token mới hơn mà backend của bạn không chấp nhận; các cách khắc phục được ghi trong tài liệu là supportsDeveloperRole: false và maxTokensField: max_tokens dưới compat. Việc phát lại yêu cầu theo định dạng harness trong một ứng dụng khách API sẽ cho bạn thấy trường nào mà backend gặp vấn đề.