Hugging Face 模型接入教程

Hugging Face 简介

Hugging Face 是全球最大的开源 AI 模型社区，托管了数十万个预训练模型。通过 Hugging Face 的 Inference API，你可以在 OpenClaw 中轻松调用这些模型，无需自建推理基础设施。

获取 API Token

首先需要获取 Hugging Face 的 API Token：

1. 注册并登录 huggingface.co
2. 进入 Settings → Access Tokens
3. 点击「New token」创建一个新的 Token
4. 选择「Read」权限即可（如需使用私有模型则选「Write」）
5. 复制生成的 Token

基础配置

在 OpenClaw 配置文件中添加 Hugging Face 供应商：

{
  "providers": {
    "huggingface": {
      "type": "openai",
      "baseUrl": "https://api-inference.huggingface.co/models/",
      "apiKey": "{{HF_API_TOKEN}}",
      "models": ["mistralai/Mistral-7B-Instruct-v0.3"]
    }
  }
}

设置密钥：

openclaw secrets set HF_API_TOKEN "hf_your_token_here"

使用 Inference Endpoints

对于生产环境，建议使用 Hugging Face 的 Inference Endpoints（专属推理端点），提供更稳定的性能和更低的延迟：

{
  "providers": {
    "hf-endpoint": {
      "type": "openai",
      "baseUrl": "https://your-endpoint-id.us-east-1.aws.endpoints.huggingface.cloud/v1",
      "apiKey": "{{HF_API_TOKEN}}",
      "models": ["tgi"]
    }
  }
}

创建 Inference Endpoint 的步骤：

1. 在 Hugging Face 上进入 Inference Endpoints 页面
2. 选择要部署的模型（如 meta-llama/Llama-3.1-8B-Instruct）
3. 选择云区域和 GPU 类型
4. 启动端点，等待状态变为「Running」

推荐模型列表

以下模型在 OpenClaw 中表现良好：

使用 Text Generation Inference (TGI) 格式

Hugging Face 的 TGI 服务兼容 OpenAI API 格式，因此在 OpenClaw 中配置时使用 openai 类型即可：

{
  "providers": {
    "hf-tgi": {
      "type": "openai",
      "baseUrl": "https://api-inference.huggingface.co/v1",
      "apiKey": "{{HF_API_TOKEN}}",
      "models": ["meta-llama/Llama-3.1-8B-Instruct"],
      "defaultModel": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}

配置模型参数

你可以为 Hugging Face 模型设置自定义推理参数：

{
  "models": {
    "hf-llama": {
      "provider": "hf-tgi",
      "model": "meta-llama/Llama-3.1-8B-Instruct",
      "temperature": 0.7,
      "maxTokens": 2048,
      "topP": 0.9
    }
  }
}

为频道分配模型

将 Hugging Face 模型分配给特定频道：

openclaw configure
# 选择频道 → 选择模型 → 选择 hf-llama

或直接编辑配置：

{
  "channels": {
    "telegram-main": {
      "model": "hf-llama"
    }
  }
}

常见问题

Q: 免费 API 有限制吗？

Hugging Face 免费 Inference API 有速率限制，约每分钟 30 次请求。生产环境建议使用 Pro 订阅或 Inference Endpoints。

Q: 模型响应速度慢怎么办？

免费 API 的模型可能处于冷启动状态，首次请求需要加载模型，可能需要数十秒。Inference Endpoints 可以保持模型常驻内存。

Q: 如何使用私有模型？

确保 API Token 有 Write 权限，然后在模型名中使用完整路径：your-org/your-private-model。

总结

Hugging Face 提供了丰富的开源模型选择，通过 Inference API 或 Inference Endpoints 接入 OpenClaw，可以灵活选择适合不同场景的模型，同时避免了自建推理服务器的复杂性。