> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ChatHuggingFace 集成

> 使用 LangChain Python 与 ChatHuggingFace 聊天模型集成。

这将帮助您开始使用 `langchain_huggingface` [聊天模型](/oss/python/langchain/models)。有关所有 `ChatHuggingFace` 功能和配置的详细文档，请访问 [API 参考](https://reference.langchain.com/python/langchain-huggingface/chat_models/huggingface/ChatHuggingFace)。有关 Hugging Face 支持的模型列表，请查看[此页面](https://huggingface.co/models)。

## 概述

### 集成详情

| 类                                                                                                                         | 包                                                                                       | 可序列化 | JS 支持 |                                                   下载量                                                  |                                                  版本                                                 |
| :------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------- | :--: | :---: | :----------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------: |
| [`ChatHuggingFace`](https://reference.langchain.com/python/langchain-huggingface/chat_models/huggingface/ChatHuggingFace) | [`langchain-huggingface`](https://reference.langchain.com/python/langchain-huggingface) | beta |   ❌   | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain_huggingface?style=flat-square\&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain_huggingface?style=flat-square\&label=%20) |

### 模型特性

| [工具调用](/oss/python/langchain/tools) | [结构化输出](/oss/python/langchain/structured-output) | [图像输入](/oss/python/langchain/messages#multimodal) | 音频输入 | 视频输入 | [令牌级流式传输](/oss/python/langchain/streaming/) | 原生异步 | [令牌使用量](/oss/python/langchain/models#token-usage) | [对数概率](/oss/python/langchain/models#log-probabilities) |
| :---------------------------------: | :----------------------------------------------: | :-----------------------------------------------: | :--: | :--: | :-----------------------------------------: | :--: | :-----------------------------------------------: | :----------------------------------------------------: |
|                  ✅                  |                         ✅                        |                         ✅                         |   ✅  |   ✅  |                      ❌                      |   ✅  |                         ✅                         |                            ❌                           |

## 设置

要访问 Hugging Face 模型，您需要创建一个 Hugging Face 帐户，获取 API 密钥，并安装 `langchain-huggingface` 集成包。

### 凭证

生成一个 [Hugging Face 访问令牌](https://huggingface.co/docs/hub/security-tokens) 并将其存储为环境变量：`HUGGINGFACEHUB_API_TOKEN`。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import getpass
import os

if not os.getenv("HUGGINGFACEHUB_API_TOKEN"):
    os.environ["HUGGINGFACEHUB_API_TOKEN"] = getpass.getpass("Enter your token: ")
```

### 安装

| 类                                                                                                                         | 包                                                                                       | 可序列化 | JS 支持 |                                                   下载量                                                  |                                                  版本                                                 |
| :------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------- | :--: | :---: | :----------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------: |
| [`ChatHuggingFace`](https://reference.langchain.com/python/langchain-huggingface/chat_models/huggingface/ChatHuggingFace) | [`langchain-huggingface`](https://reference.langchain.com/python/langchain-huggingface) |   ❌  |   ❌   | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain_huggingface?style=flat-square\&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain_huggingface?style=flat-square\&label=%20) |

### 模型特性

| [工具调用](/oss/python/langchain/tools) | [结构化输出](/oss/python/langchain/structured-output) | [图像输入](/oss/python/langchain/messages#multimodal) | 音频输入 | 视频输入 | [令牌级流式传输](/oss/python/langchain/streaming/) | 原生异步 | [令牌使用量](/oss/python/langchain/models#token-usage) | [对数概率](/oss/python/langchain/models#log-probabilities) |
| :---------------------------------: | :----------------------------------------------: | :-----------------------------------------------: | :--: | :--: | :-----------------------------------------: | :--: | :-----------------------------------------------: | :----------------------------------------------------: |
|                  ✅                  |                         ✅                        |                         ❌                         |   ❌  |   ❌  |                      ❌                      |   ❌  |                         ❌                         |                            ❌                           |

## 设置

要访问 `langchain_huggingface` 模型，您需要创建一个 `Hugging Face` 帐户，获取 API 密钥，并安装 `langchain-huggingface` 集成包。

### 凭证

您需要将一个 [Hugging Face 访问令牌](https://huggingface.co/docs/hub/security-tokens) 保存为环境变量：`HUGGINGFACEHUB_API_TOKEN`。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import getpass
import os

os.environ["HUGGINGFACEHUB_API_TOKEN"] = getpass.getpass(
    "Enter your Hugging Face API key: "
)
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -qU  langchain-huggingface text-generation transformers google-search-results numexpr langchainhub sentencepiece jinja2 bitsandbytes accelerate
```

## 实例化

您可以通过两种不同的方式实例化 `ChatHuggingFace` 模型，要么从 `HuggingFaceEndpoint`，要么从 `HuggingFacePipeline`。

### `HuggingFaceEndpoint`

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint

llm = HuggingFaceEndpoint(
    repo_id="deepseek-ai/DeepSeek-R1-0528",
    task="text-generation",
    max_new_tokens=512,
    do_sample=False,
    repetition_penalty=1.03,
    provider="auto",  # 让 Hugging Face 为您选择最佳提供商
)

chat_model = ChatHuggingFace(llm=llm)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
The token has not been saved to the git credentials helper. Pass `add_to_git_credential=True` in this function directly or `--add-to-git-credential` if using via `huggingface-cli` if you want to set the git credential as well.
Token is valid (permission: fineGrained).
Your token has been saved to /Users/isaachershenson/.cache/huggingface/token
Login successful
```

现在让我们利用 [推理提供商](https://huggingface.co/docs/inference-providers) 在特定的第三方提供商上运行模型

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
llm = HuggingFaceEndpoint(
    repo_id="deepseek-ai/DeepSeek-R1-0528",
    task="text-generation",
    provider="hyperbolic",  # 在此处设置您的提供商
    # provider="nebius",
    # provider="together",
)

chat_model = ChatHuggingFace(llm=llm)
```

### `HuggingFacePipeline`

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_huggingface import ChatHuggingFace, HuggingFacePipeline

llm = HuggingFacePipeline.from_model_id(
    model_id="HuggingFaceH4/zephyr-7b-beta",
    task="text-generation",
    pipeline_kwargs=dict(
        max_new_tokens=512,
        do_sample=False,
        repetition_penalty=1.03,
    ),
)

chat_model = ChatHuggingFace(llm=llm)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
config.json:   0%|          | 0.00/638 [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model.safetensors.index.json:   0%|          | 0.00/23.9k [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Downloading shards:   0%|          | 0/8 [00:00<?, ?it/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model-00001-of-00008.safetensors:   0%|          | 0.00/1.89G [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model-00002-of-00008.safetensors:   0%|          | 0.00/1.95G [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model-00003-of-00008.safetensors:   0%|          | 0.00/1.98G [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model-00004-of-00008.safetensors:   0%|          | 0.00/1.95G [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model-00005-of-00008.safetensors:   0%|          | 0.00/1.98G [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model-00006-of-00008.safetensors:   0%|          | 0.00/1.95G [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model-00007-of-00008.safetensors:   0%|          | 0.00/1.98G [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
model-00008-of-00008.safetensors:   0%|          | 0.00/816M [00:00<?, ?B/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Loading checkpoint shards:   0%|          | 0/8 [00:00<?, ?it/s]
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
generation_config.json:   0%|          | 0.00/111 [00:00<?, ?B/s]
```

### 使用量化进行实例化

要运行模型的量化版本，您可以按如下方式指定 `bitsandbytes` 量化配置：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from transformers import BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype="float16",
    bnb_4bit_use_double_quant=True,
)
```

并将其作为 `model_kwargs` 的一部分传递给 `HuggingFacePipeline`：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
llm = HuggingFacePipeline.from_model_id(
    model_id="HuggingFaceH4/zephyr-7b-beta",
    task="text-generation",
    pipeline_kwargs=dict(
        max_new_tokens=512,
        do_sample=False,
        repetition_penalty=1.03,
        return_full_text=False,
    ),
    model_kwargs={"quantization_config": quantization_config},
)

chat_model = ChatHuggingFace(llm=llm)
```

## 调用

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.messages import (
    HumanMessage,
    SystemMessage,
)

messages = [
    SystemMessage(content="You're a helpful assistant"),
    HumanMessage(
        content="What happens when an unstoppable force meets an immovable object?"
    ),
]

ai_msg = chat_model.invoke(messages)
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
print(ai_msg.content)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
According to the popular phrase and hypothetical scenario, when an unstoppable force meets an immovable object, a paradoxical situation arises as both forces are seemingly contradictory. On one hand, an unstoppable force is an entity that cannot be stopped or prevented from moving forward, while on the other hand, an immovable object is something that cannot be moved or displaced from its position.

In this scenario, it is un
```

***

## API 参考

有关所有 `ChatHuggingFace` 功能和配置的详细文档，请访问 [API 参考](https://reference.langchain.com/python/langchain-huggingface/chat_models/huggingface/ChatHuggingFace)

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/chat/huggingface.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>