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.

Dùng thử Apidog ngay hôm nay

Hướng dẫn này đ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.

Lưu ý: dsh là bản xem trước dành cho nhà phát triển. README cảnh báo 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 khớp với phiên bản bạn đã cài đặt trước khi áp dụng vào môi trường sản xuấ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 để cấu hình 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 có thể thay thế.

Ba lý do phổ biến để đổi mô hình:

• Chi phí: Phiên tác nhân tiêu tốn token nhanh vì mọi kết quả công cụ đều quay lại ngữ cảnh. Bạn có thể định tuyến phiên thông thường sang mô hình rẻ hơn, hoặc dùng DeepSeek V4-Flash thay cho V4-Pro, mà không thay đổi quy trình làm việc.
• Tính cục bộ của dữ liệu: Nếu codebase không thể rời khỏi hạ tầng nội bộ, hãy trỏ nhà cung cấp tới mô hình chạy trên phần cứng của bạn. Prompt, nội dung tệp và đầu ra công cụ sẽ không đi qua mạng.
• Phát triển cục bộ: Khi xây dựng plugin hoặc kiểm tra hành vi tác nhân, một mô hình nhỏ chạy cục bộ giúp bạn lặp nhanh mà không tốn tín dụng API hoặc phụ thuộc mạng.

Thiết kế này phù hợp với kiến trúc dsh: mọi thứ trong harness đều là plugin, và bộ chuyển đổi mô hình là một thành phần có thể thay thế. Các tuyến nhà cung cấp thuộc plugin dsh-llm-pi-ai, được mô tả trong danh mục cấu hình plugin là nơi chứa “các tuyến nhà cung cấp mà thể hiện này sở hữu”.

Phần bạn cần cấu hình 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. Bạn cũng có thể tạo chúng trong giao diện web tại Cài đặt → Mô hình.

Ví dụ 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]

Ý nghĩa từng khóa:

• my-gateway: ID nhà cung cấp. Đây là định danh lâu dài, nên đặt tên ổn định; tên hiển thị trong giao diện được cấu hình riêng.
• apiKeyEnv: Tên biến môi trường chứa khóa API. Không đặt bí mật trực tiếp vào settings.yaml.
• api: Giao thức truyền tải. Với điểm cuối tương thích OpenAI, dùng openai-completions.
• baseURL: URL gốc mà harness gửi yêu cầu tới.
• models: Danh sách model ID có sẵn từ nhà cung cấp. Mỗi id phải khớp chính xác với ID mà điểm cuối mong đợi trong request.
• input: Khai báo kiểu đầu vào cho từng mô hình. Mô hình tùy chỉnh mặc định chỉ nhận văn bản. Với mô hình thị giác, phải thêm input: [text, image] để ảnh đính kèm được gửi đi.
• defaultInput: Giá trị đầu vào mặc định ở cấp nhà cung cấp. input tại cấp mô hình sẽ ghi đè giá trị này.
• compat: Các cờ tương thích cho backend không hoàn toàn tuân theo hành vi OpenAI chuẩn:
  • supportsDeveloperRole: false: dùng khi backend từ chối vai trò developer.
  • maxTokensField: max_tokens: dùng khi backend yêu cầu tên trường giới hạn đầu ra cũ hơn.

Ví dụ cấu hình compat theo từng mô hình:

llm-pi-ai:
  providers:
    legacy-gateway:
      apiKeyEnv: LEGACY_GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
          compat:
            supportsDeveloperRole: false
            maxTokensField: max_tokens

Khi thêm nhà cung cấp tùy chỉnh bằng giao diện web, tùy chọn Fetch available models sẽ gọi tuyến GET /models tương thích OpenAI để tự động điền danh sách mô hình. Nếu endpoint của bạn có tuyến này, không cần nhập từng ID thủ công.

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

Bí mật được lưu trữ trong:

$DSH_HOME/.credentials.yaml

Sau khi lưu khóa bằng giao diện, dsh chỉ trả về mô tả đã được che bớt. Giá trị thực không được hiển thị lại.

Tóm lại:

• settings.yaml chứa tham chiếu như apiKeyEnv.
• .credentials.yaml chứa thông tin xác thực.
• Không commit khóa API vào kho mã nguồn.
• Bạn có thể xoay vòng khóa mà không phải sửa cấu hình nhà cung cấp.

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

Ollama cung cấp API tương thích OpenAI tại http://localhost:11434/v1, theo hướng dẫn tương thích OpenAI của Ollama.

Vì dsh hỗ trợ openai-completions với bất kỳ URL cơ sở nào, bạn có thể cấu hình Ollama như sau:

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

Xác minh: Tài liệu dsh không hiển thị ví dụ Ollama cụ thể. Công thức này áp dụng schema nhà cung cấp tùy chỉnh của dsh vào endpoint tương thích OpenAI được Ollama ghi tài liệu. Hãy kiểm tra trên bản cài đặt của bạn trước khi triển khai nội bộ.

Các bước triển khai

1. Khởi động Ollama.
2. Tải mô hình trước:

   ollama pull gpt-oss:20b

1. Kiểm tra tên model chính xác:

   ollama list

1. Đặt biến môi trường. Ollama cục bộ không yêu cầu API key, nhưng schema cần tham chiếu xác thực:

   export OLLAMA_API_KEY=ollama

1. Thêm cấu hình vào $DSH_HOME/settings.yaml.
2. Mở dsh và chọn model trong Cài đặt → Mô hình.

id trong YAML phải khớp với tag do Ollama cung cấp, bao gồm cả phần tag như gpt-oss:20b.

Bạn có thể xem thiết lập cục bộ chi tiết hơn trong cách chạy GPT-OSS bằng Ollama. Cùng mẫu này có thể dùng cho các mô hình mã nguồn mở khác như Kimi K3 nếu phần cứng đáp ứng được.

Trước khi cấu hình dsh, hãy kiểm tra endpoint trực tiếp:

curl http://localhost:11434/v1/models

Hoặc gửi GET http://localhost:11434/v1/models trong Apidog.

Nếu endpoint trả về danh sách mô hình, nghĩa là:

• URL cơ sở đúng.
• Ollama đang chạy.
• Tính năng Fetch available models của dsh có thể hoạt động.

Nếu endpoint không phản hồi, thay đổi cấu hình harness sẽ không giải quyết được vấn đề.

Các harness tác nhân phụ thuộc nhiều vào tool calling và ngữ cảnh dài. Mô hình cục bộ nhỏ phù hợp để kiểm tra vòng lặp hoặc phát triển plugin, nhưng có thể lập kế hoạch kém hơn và bỏ qua tool call thường xuyên hơn mô hình tiên tiến.

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

Với nhà cung cấp được lưu trữ, hãy ưu tiên dịch vụ có tài liệu xác nhận tương thích OpenAI.

Alibaba Cloud Model Studio (DashScope) cung cấp trang tương thích OpenAI, trong đó ghi rõ endpoint /compatible-mode/v1 cho các mô hình Qwen.

Ví dụ endpoint dành cho workspace Singapore:

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

Cấu hình 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

Các bước triển khai

1. Tạo hoặc lấy API key từ Model Studio.
2. Đặt biến môi trường:

   export DASHSCOPE_API_KEY="your-api-key"

1. Thay {WorkspaceId} bằng workspace thực tế của bạn.
2. Kiểm tra danh sách model hiện tại của nhà cung cấp.
3. Thêm model ID vào models.
4. Kiểm tra endpoint /models trước khi chạy phiên tác nhân.

Bạn có thể tham khảo hướng dẫn API Qwen 3.8 để xem thông tin tổng quan về các model.

Mẫu cấu hình này cũng áp dụng cho các nhà cung cấp tương thích OpenAI khác, như:

• API Kimi của Moonshot
• OpenRouter
• Triển khai vLLM
• Gateway nội bộ của công ty

Thông thường, bạn chỉ cần đổi ba phần:

apiKeyEnv: PROVIDER_API_KEY
baseURL: https://provider.example/v1
models:
  - id: provider-model-id

Nếu bạn từng cấu hình các mô hình mã nguồn mở trong Codex, khối YAML của dsh có vai trò tương tự cấu hình model_providers của Codex.

Lưu ý cho endpoint được lưu trữ

Nếu endpoint trả về lỗi liên quan đến vai trò hoặc trường token, hãy thử cấu hình tương thích:

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
          compat:
            supportsDeveloperRole: false

Nếu backend từ chối trường giới hạn token, thử:

compat:
  maxTokensField: max_tokens

Với model thị giác, khai báo rõ đầu vào:

models:
  - id: vision-model-id
    input: [text, image]

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

Bạn không cần tạo khối tùy chỉnh cho các đám mây chính thống. dsh cung cấp nhà cung cấp danh mục cho DeepSeek, Anthropic và OpenAI, nơi thiết lập chủ yếu là thêm khóa API.

Một số mục danh mục có luồng xác thực riêng:

• Bedrock: dùng thông tin xác thực AWS.
• Vertex: yêu cầu dự án ADC.
• Azure: cần phiên bản API tương ứng.
• Codex: xác thực qua OAuth.

Nhà cung cấp danh mục là lựa chọn ít cấu hình nhất khi bạn muốn chạy Claude hoặc GPT trong harness.

Đây cũng là cách phổ biến để dùng DeepSeek V4-Pro, API ra mắt vào tháng 8 năm 2026 cùng với harness. Xem tài liệu tại api-docs.deepseek.com.

Dùng nhà cung cấp tùy chỉnh khi danh mục chưa đáp ứng nhu cầu của bạn, ví dụ:

• Mô hình cục bộ
• Gateway nội bộ
• Nhà cung cấp theo khu vực
• Bộ tổng hợp hỗ trợ OpenAI-compatible API

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

Thêm nhà cung cấp chỉ làm model của nó xuất hiện trong danh sách. Bạn vẫn cần chọn model tại Cài đặt → Mô hình để đặt mặc định cho các phiên mới.

Hai hành vi cần nhớ:

1. Phiên hiện có giữ nguyên model ban đầu.
   
   Mỗi phiên ghi lại model khi bắt đầu. Đổi model mặc định giữa chừng không sửa lịch sử hoặc thay model của phiên đang chạy.

2. Xóa nhà cung cấp đang sở hữu model mặc định sẽ chặn trình soạn thảo.
   
   Bạn phải chọn model mới; harness không tự đoán model thay thế.

Việc ghim model theo phiên rất quan trọng để tái tạo kết quả. Khi so sánh dsh với các harness khác, chẳng hạn trong bài DeepSeek Harness so với Claude Code, bạn có thể tin rằng bản ghi phiên phản ánh một model nhất quán.

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

baseURL sai hoặc không thể truy cập

Đây là lỗi phổ biến nhất.

Kiểm tra URL có kết thúc đúng vị trí mà giao thức yêu cầu không:

• OpenAI-compatible: thường là /v1
• DashScope: /compatible-mode/v1

Sau đó gọi trực tiếp:

curl -H "Authorization: Bearer $KEY" \
  "{baseURL}/models"

Ví dụ với một endpoint tương thích OpenAI:

curl -H "Authorization: Bearer $GATEWAY_API_KEY" \
  https://gateway.example/v1/models

Bạn cũng có thể dùng Tải xuống Apidog để gửi cùng header mà harness sẽ gửi và xem mã trạng thái cùng response body thực tế.

Nếu phát triển ngoại tuyến hoặc nhà cung cấp không ổn định, hãy mock các phản hồi:

• /models
• /chat/completions

Sau đó trỏ baseURL của dsh tới mock server trong khi xây dựng.

Biến môi trường bị thiếu hoặc trống

apiKeyEnv chỉ đặt tên biến môi trường; nó không tự tạo biến.

Ví dụ:

apiKeyEnv: GATEWAY_API_KEY

Bạn vẫn phải đặt giá trị:

export GATEWAY_API_KEY="your-api-key"

Nếu biến không tồn tại trong môi trường đang chạy dsh, request có thể không được xác thực và trả về 401.

Kiểm tra trong đúng ngữ cảnh khởi chạy:

echo $GATEWAY_API_KEY

Đừng chỉ kiểm tra trong một terminal bất kỳ. Tiến trình chạy từ GUI hoặc service manager có thể không kế thừa cấu hình shell của bạn.

Không khớp phương thức đầu vào

Nếu bạn đính kèm ảnh nhưng model không nhận được, hoặc request lỗi, hãy kiểm tra input.

Mô hình tùy chỉnh mặc định chỉ hỗ trợ văn bản:

models:
  - id: vision-model-id
    input: [text, image]

Nếu mọi model của một nhà cung cấp đều hỗ trợ ảnh, đặt mặc định ở cấp route:

llm-pi-ai:
  providers:
    my-provider:
      apiKeyEnv: PROVIDER_API_KEY
      api: openai-completions
      baseURL: https://provider.example/v1
      defaultInput: [text, image]
      models:
        - id: model-a
        - id: model-b

Bất thường giao thức

Nếu lỗi đề cập đến vai trò không được hỗ trợ hoặc token parameter bị từ chối, thêm compat:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

Hai cờ này là các lựa chọn tương thích được tài liệu dsh ghi nhận.

Hôm qua vẫn hoạt động

dsh là bản xem trước dành cho nhà phát triển. Để giảm rủi ro:

1. Ghim phiên bản dsh khi triển khai.
2. Đọc release notes trước khi nâng cấp.
3. Kiểm tra lại schema settings.yaml.
4. Xác minh cấu hình trong môi trường staging.

Kho lưu trữ deepseek-harness là nguồn thông tin đáng tin cậy hơn bất kỳ bài blog nào, bao gồm bài này.

Nhà cung cấp model chỉ là một nửa của việc tùy chỉnh harness. Nửa còn lại là công cụ mà tác nhân gọi được. Bạn có thể kết nối trực tiếp quy trình API của mình; xem thêm 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 nhắc Ollama theo tên. Tuy nhiên, dsh hỗ trợ các endpoint dùng giao thức openai-completions, còn Ollama có API tương thích OpenAI tại http://localhost:11434/v1.

Công thức Ollama ở trên kết hợp hai phần đã được ghi tài liệu. Hãy kiểm tra trên bản cài đặt của bạn vì dsh là bản xem trước và schema có thể thay đổi giữa các bản phát hành.

dsh lưu trữ khóa API ở đâu?

Khóa được lưu trong:

$DSH_HOME/.credentials.yaml

Giao diện chỉ hiển thị mô tả đã che bớt sau khi lưu. settings.yaml chỉ chứa tham chiếu, chẳng hạn tên apiKeyEnv, không chứa khóa văn bản thuần túy.

Tôi có thể chạy model khác nhau cho các phiên khác nhau không?

Có.

Việc chọn model chỉ đặt mặc định cho phiên mới. Các phiên hiện có tiếp tục dùng model mà chúng được bắt đầu cùng.

Ví dụ, bạn có thể:

1. Dùng DeepSeek V4-Flash cho phiên thông thường.
2. Chuyển model mặc định sang model mạnh hơn cho một tác vụ khó.
3. Giữ nguyên các phiên trước đó mà không bị ảnh hưởng.

Endpoint tùy chỉnh trả về lỗi, nhưng cùng request chạy được trong curl. Tôi nên làm gì?

So sánh chính xác payload mà harness gửi với payload curl đang hoạt động.

Harness có thể gửi:

• Vai trò developer
• Trường giới hạn token mới hơn

Nếu backend không hỗ trợ, cấu hình:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

Hãy phát lại request theo định dạng của harness trong một API client để xác định chính xác trường mà backend từ chối.