与 Hugging Face 的 LLM 交互有很多方式，可以在本地使用，也可以通过 Hugging Face 的 Inference Providers 使用。Hugging Face 本身提供了多个 Python 包来实现访问，LlamaIndex 将它们封装为 LLM 实体：

• transformers 包：使用 llama_index.llms.HuggingFaceLLM
• Hugging Face Inference Providers，由 huggingface_hub[inference] 封装：使用 llama_index.llms.HuggingFaceInferenceAPI

这两者的可能组合非常多，所以本 notebook 只详细介绍其中几种。我们以 Hugging Face 的文本生成任务为例。

在下面一行中，我们安装本演示所需的软件包：

• HuggingFaceLLM 需要 transformers[torch]
• HuggingFaceInferenceAPI 需要 huggingface_hub[inference]
• Z shell（zsh）需要引号

%pip install llama-index-llms-huggingface # for local inference
%pip install llama-index-llms-huggingface-api # for remote inference

!pip install "transformers[torch]" "huggingface_hub[inference]"

如果你在 Colab 中打开这个 Notebook，可能需要先安装 LlamaIndex 🦙。

!pip install llama-index

设置完成后，我们来试试：

设置 Hugging Face 账户

首先，你需要创建一个 Hugging Face 账户并获取令牌。你可以在此处注册。然后需要在此处创建令牌。

终端窗口

export HUGGING_FACE_TOKEN=hf_your_token_here

import os
from typing import List, Optional

from llama_index.llms.huggingface import HuggingFaceLLM
from llama_index.llms.huggingface_api import HuggingFaceInferenceAPI

HF_TOKEN: Optional[str] = os.getenv("HUGGING_FACE_TOKEN")
# NOTE: None default will fall back on Hugging Face's token storage
# when this token gets used within HuggingFaceInferenceAPI

通过 Inference Providers 使用模型

使用开源模型最简单的方式是使用 Hugging Face Inference Providers。我们使用 DeepSeek R1 模型，它非常适合复杂任务。

使用推理提供商，你可以在推理提供商的无服务器基础设施上使用模型。

remotely_run = HuggingFaceInferenceAPI(
    model_name="deepseek-ai/DeepSeek-R1-0528",
    token=HF_TOKEN,
    provider="auto",  # this will use the best provider available
)

我们也可以指定首选的推理提供商。我们使用 together 提供商。

remotely_run = HuggingFaceInferenceAPI(
    model_name="Qwen/Qwen3-235B-A22B",
    token=HF_TOKEN,
    provider="together",  # this will use the best provider available
)

在本地使用开源模型

首先，我们使用一个针对本地推理优化的开源模型。该模型首次调用时会下载到本地 Hugging Face 模型缓存，并实际在你本机的硬件上运行。

我们使用 Gemma 3N E4B 模型，它针对本地推理进行了优化。

locally_run = HuggingFaceLLM(model_name="google/gemma-3n-E4B-it")

使用专用 Inference Endpoint

我们也可以为模型启动专用的 Inference Endpoint，并用它来运行模型。

endpoint_server = HuggingFaceInferenceAPI(
    model="https://(<your-endpoint>.eu-west-1.aws.endpoints.huggingface.cloud"
)

使用本地推理引擎（vLLM 或 TGI）

我们也可以使用 vLLM 或 TGI 等本地推理引擎来运行模型。

# You can also connect to a model being served by a local or remote
# Text Generation Inference server
tgi_server = HuggingFaceInferenceAPI(model="http://localhost:8080")

HuggingFaceInferenceAPI 的补全底层是 Hugging Face 的文本生成任务。

completion_response = remotely_run_recommended.complete("To infinity, and")
print(completion_response)

 beyond!
The Infinity Wall Clock is a unique and stylish way to keep track of time. The clock is made of a durable, high-quality plastic and features a bright LED display. The Infinity Wall Clock is powered by batteries and can be mounted on any wall. It is a great addition to any home or office.

设置分词器

如果你要修改 LLM，还应更改全局分词器以保持一致！

from llama_index.core import set_global_tokenizer
from transformers import AutoTokenizer

set_global_tokenizer(
    AutoTokenizer.from_pretrained("HuggingFaceH4/zephyr-7b-alpha").encode
)

如果你好奇的话，还封装了以下其他 Hugging Face Inference API 任务：

• llama_index.llms.HuggingFaceInferenceAPI.chat：对话任务
• llama_index.embeddings.HuggingFaceInferenceAPIEmbedding：特征提取任务

是的，Hugging Face 嵌入模型也通过以下方式得到支持：

• transformers[torch]：由 HuggingFaceEmbedding 封装
• huggingface_hub[inference]：由 HuggingFaceInferenceAPIEmbedding 封装

上述两者都继承自 llama_index.embeddings.base.BaseEmbedding。