Hugging Face (suy luận)

Các nhà cung cấp suy luận của Hugging Face cung cấp một bộ định tuyến hoàn thành hội thoại tương thích với OpenAI cho nhiều mô hình được lưu trữ (DeepSeek, Llama và nhiều mô hình khác) dưới một token duy nhất. OpenClaw chỉ giao tiếp với điểm cuối hoàn thành hội thoại; đối với chuyển văn bản thành hình ảnh, embedding hoặc giọng nói, hãy sử dụng trực tiếp các ứng dụng khách suy luận HF.

Thuộc tính	Giá trị
ID nhà cung cấp	huggingface
Plugin	đi kèm (được bật theo mặc định, không cần bước cài đặt)
Biến môi trường xác thực	HUGGINGFACE_HUB_TOKEN hoặc HF_TOKEN (token chi tiết)
API	Tương thích với OpenAI (https://router.huggingface.co/v1)
Thanh toán	Một token HF duy nhất; mức giá tuân theo mức phí của nhà cung cấp và có gói miễn phí

​

Bắt đầu

1. Tạo token chi tiết

   Truy cập Hugging Face Settings Tokens và tạo một token chi tiết mới.

   Token phải được bật quyền Make calls to Inference Providers, nếu không các yêu cầu API sẽ bị từ chối.

2. Chạy quy trình thiết lập ban đầu

   Chọn Hugging Face trong danh sách thả xuống nhà cung cấp, sau đó nhập khóa API khi được nhắc:

   openclaw onboard --auth-choice huggingface-api-key
   
3. Chọn mô hình mặc định

   Trong danh sách thả xuống Default Hugging Face model, hãy chọn một mô hình. Danh sách được tải từ Inference API khi token hợp lệ; nếu không, OpenClaw sẽ hiển thị danh mục tích hợp bên dưới. Lựa chọn của bạn được lưu dưới dạng agents.defaults.model.primary:

   {
     agents: {
       defaults: {
         model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
       },
     },
   }
   
4. Xác minh mô hình có sẵn

   openclaw models list --provider huggingface
   

​

Thiết lập không tương tác

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"

Đặt huggingface/deepseek-ai/DeepSeek-R1 làm mô hình mặc định.

​

ID mô hình

Tham chiếu mô hình có dạng huggingface/<org>/<model> (ID kiểu Hub). Danh mục tích hợp của OpenClaw:

Mô hình	Tham chiếu (thêm tiền tố huggingface/)
DeepSeek R1	deepseek-ai/DeepSeek-R1
DeepSeek V3.1	deepseek-ai/DeepSeek-V3.1
GPT-OSS 120B	openai/gpt-oss-120b

Khi token hợp lệ, OpenClaw cũng phát hiện mọi mô hình khác từ GET https://router.huggingface.co/v1/models trong quá trình thiết lập ban đầu và khi Gateway khởi động, vì vậy danh mục của bạn có thể bao gồm nhiều hơn đáng kể so với ba mô hình trên. Bạn có thể thêm :fastest hoặc :cheapest vào bất kỳ ID mô hình nào; bộ định tuyến của HF sẽ định tuyến đến nhà cung cấp suy luận tương ứng. Đặt thứ tự nhà cung cấp mặc định trong cài đặt Nhà cung cấp suy luận.

​

Cấu hình nâng cao

Phát hiện mô hình và danh sách thả xuống khi thiết lập ban đầu

OpenClaw phát hiện các mô hình bằng:

GET https://router.huggingface.co/v1/models
Authorization: Bearer $HUGGINGFACE_HUB_TOKEN   # hoặc $HF_TOKEN

Phản hồi theo kiểu OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

Khi đã cấu hình khóa (qua quy trình thiết lập ban đầu, HUGGINGFACE_HUB_TOKEN hoặc HF_TOKEN), danh sách thả xuống Default Hugging Face model trong quá trình thiết lập tương tác sẽ được điền từ điểm cuối này. Khi Gateway khởi động, lệnh gọi tương tự được thực hiện lại để làm mới danh mục. Các mô hình được phát hiện sẽ được hợp nhất với danh mục tích hợp ở trên (dùng cho siêu dữ liệu như cửa sổ ngữ cảnh và chi phí khi ID trùng khớp). Nếu yêu cầu thất bại, không trả về dữ liệu hoặc chưa đặt khóa, OpenClaw chỉ sử dụng danh mục tích hợp.

Tắt tính năng phát hiện mà không xóa nhà cung cấp:

openclaw config set plugins.entries.huggingface.config.discovery.enabled false

Tên mô hình, bí danh và hậu tố chính sách

• Tên từ API: các mô hình được phát hiện sử dụng name, title hoặc display_name của API khi có; nếu không, OpenClaw suy ra tên từ ID mô hình (ví dụ: deepseek-ai/DeepSeek-R1 trở thành “DeepSeek R1”).
• Ghi đè tên hiển thị: đặt nhãn tùy chỉnh cho từng mô hình trong cấu hình:

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}

• Hậu tố chính sách: :fastest và :cheapest là quy ước của bộ định tuyến HF, không phải nội dung mà OpenClaw viết lại: hậu tố được gửi nguyên văn như một phần của ID mô hình và bộ định tuyến của HF chọn nhà cung cấp suy luận tương ứng. Thêm từng biến thể dưới dạng một mục riêng trong models.providers.huggingface.models (hoặc trong model.primary) nếu bạn muốn có bí danh riêng cho từng hậu tố.
• Hợp nhất cấu hình: các mục hiện có trong models.providers.huggingface.models (ví dụ: trong models.json) được giữ lại khi hợp nhất cấu hình, vì vậy mọi name, alias tùy chỉnh hoặc tùy chọn mô hình bạn đặt ở đó vẫn tồn tại sau khi khởi động lại.

Thiết lập môi trường và daemon

Nếu Gateway chạy dưới dạng daemon (launchd/systemd), hãy đảm bảo HUGGINGFACE_HUB_TOKEN hoặc HF_TOKEN khả dụng cho tiến trình đó (ví dụ: trong ~/.openclaw/.env hoặc thông qua env.shellEnv).

OpenClaw chấp nhận cả HUGGINGFACE_HUB_TOKEN và HF_TOKEN. Nếu cả hai đều được đặt, HUGGINGFACE_HUB_TOKEN được ưu tiên.

Cấu hình: DeepSeek R1 với phương án dự phòng

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-R1",
        fallbacks: ["huggingface/openai/gpt-oss-120b"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

Cấu hình: DeepSeek với các biến thể rẻ nhất và nhanh nhất

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheapest)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fastest)" },
      },
    },
  },
}

Cấu hình: DeepSeek + GPT-OSS với bí danh

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-V3.1",
        fallbacks: ["huggingface/openai/gpt-oss-120b"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

​

Liên quan

Lựa chọn mô hình

Tổng quan về tất cả nhà cung cấp, tham chiếu mô hình và hành vi chuyển đổi dự phòng.

Lựa chọn mô hình

Cách chọn và cấu hình mô hình.

Tài liệu Nhà cung cấp suy luận

Tài liệu chính thức về Nhà cung cấp suy luận của Hugging Face.

Cấu hình

Tài liệu tham chiếu cấu hình đầy đủ.