# Fun-ASR-Nano

## 概述

Fun-ASR-Nano 是由阿里巴巴达摩院 FunAudioLLM 团队开发的 800M 参数端到端语音识别模型。它在中文、英文和日文 ASR 基准测试中达到了最先进的性能，同时体积显著小于同类模型。

该模型在 [Fun-ASR: An Industrial-Grade Speech Recognition System](https://huggingface.co/papers/2509.12508) 中提出。

### 架构

Fun-ASR-Nano 由三个组件组成：

1. **音频编码器**（SenseVoiceEncoderSmall）：一个 70 层的 SANM（带 FSMN 记忆的自注意力）编码器，将多头自注意力与前馈顺序记忆网络相结合，以实现高效的语音特征提取。

2. **Audio Adaptor**：一个 2 层 Transformer，用于将编码器输出（512 维）投影到 LLM 维度（1024 维）。

3. **语言模型**（Qwen3-0.6B）：一个 28 层的因果语言模型，以自回归方式生成转录文本。

### 主要功能

- **中文、英文和日文**，包含 7 种中文方言和 26 种地区口音
- 用于领域特定词汇的**热词定制**
- **原生标点**输出（无需单独的标点模型）

## 用法

### 单次推理

```python
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor

model_id = "FunAudioLLM/Fun-ASR-Nano-2512-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForSpeechSeq2Seq.from_pretrained(model_id, device_map="auto")

audio_url = "https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512/resolve/main/example/en.mp3"
inputs = processor.apply_transcription_request(audio=audio_url).to(model.device)

generated_ids = model.generate(**inputs, max_new_tokens=200)
generated_ids = generated_ids[:, inputs.input_ids.shape[1]:]
print(processor.decode(generated_ids, skip_special_tokens=True)[0])
```

### 批量推理

```python
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor

model_id = "FunAudioLLM/Fun-ASR-Nano-2512-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForSpeechSeq2Seq.from_pretrained(model_id, device_map="auto")

audio_urls = [
    "https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512/resolve/main/example/zh.mp3",
    "https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512/resolve/main/example/en.mp3",
]
languages = ["zh", "en"]
inputs = processor.apply_transcription_request(audio=audio_urls, language=languages).to(model.device)

generated_ids = model.generate(**inputs, max_new_tokens=200)
generated_ids = generated_ids[:, inputs.input_ids.shape[1]:]
print(processor.decode(generated_ids, skip_special_tokens=True))
```

### 自定义提示词和热词

通过 `prompt` 传递上下文信息，通过 `keywords` 传递热词；检查点的聊天模板会构建完整的转录指令。`language` 接受中文、英文和日文的完整名称或 ISO 代码。

```python
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor

model_id = "FunAudioLLM/Fun-ASR-Nano-2512-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForSpeechSeq2Seq.from_pretrained(model_id, device_map="auto")

audio_url = "https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512/resolve/main/example/en.mp3"
inputs = processor.apply_transcription_request(
    audio=audio_url,
    prompt="A tribal story involving a chieftain and a boy.",
    keywords=["tribal chieftain", "fifty pieces of gold"],
).to(model.device)

generated_ids = model.generate(**inputs, max_new_tokens=200)
generated_ids = generated_ids[:, inputs.input_ids.shape[1]:]
print(processor.decode(generated_ids, skip_special_tokens=True)[0])
```

### 训练

将目标转录文本通过`transcription`传递给`apply_transcription_request`，返回的`labels`用于计算损失。

```python
from datasets import Audio, load_dataset
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor

model_id = "FunAudioLLM/Fun-ASR-Nano-2512-hf"
NUM_SAMPLES = 2

processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForSpeechSeq2Seq.from_pretrained(model_id, device_map="auto")
model.train()

ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
ds = ds.cast_column("audio", Audio(sampling_rate=processor.feature_extractor.sampling_rate))
speech_samples = [el["array"] for el in ds["audio"][:NUM_SAMPLES]]
text_samples = ds["text"][:NUM_SAMPLES]

inputs = processor.apply_transcription_request(speech_samples, language="en", transcription=text_samples)
inputs.to(model.device, dtype=model.dtype)

loss = model(**inputs).loss
print("Loss:", loss.item())
loss.backward()
```

### 使用 `torch.compile` 进行推理

```python
import torch
from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor, CompileConfig

model_id = "FunAudioLLM/Fun-ASR-Nano-2512-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForSpeechSeq2Seq.from_pretrained(model_id, device_map="auto")

audio_url = "https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512/resolve/main/example/en.mp3"
inputs = processor.apply_transcription_request(audio=audio_url).to(model.device)

with torch.inference_mode():
    generated_ids = model.generate(
        **inputs,
        max_new_tokens=200,
        compile_config=CompileConfig(),
    )
generated_ids = generated_ids[:, inputs.input_ids.shape[1]:]
print(processor.decode(generated_ids, skip_special_tokens=True)[0])
```

## FunAsrNanoConfig[[transformers.FunAsrNanoConfig]]

#### transformers.FunAsrNanoConfig[[transformers.FunAsrNanoConfig]]

```python
transformers.FunAsrNanoConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, adaptor_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_token_id: int = 151646, initializer_range: float = 0.02, tie_word_embeddings: bool = True)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/configuration_fun_asr_nano.py#L77)

**参数：**

adaptor_config (`dict` 或 `FunAsrNanoAdaptorConfig`，*可选*)：双向音频适配器的配置。

audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：音频骨干网络的配置对象或字典。

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：文本骨干网络的配置对象或字典。

audio_token_id (`int`，*可选*，默认为 `151646`)：用作输入音频占位符的音频 token 索引。

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

这是用于存储 FunAsrNanoModel 配置的类。它根据指定的参数实例化 Fun Asr Nano 模型，并定义模型架构。使用默认值实例化配置将生成与 [FunAudioLLM/Fun-ASR-Nano-2512-hf](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512-hf) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## FunAsrNanoEncoderConfig[[transformers.FunAsrNanoEncoderConfig]]

#### transformers.FunAsrNanoEncoderConfig[[transformers.FunAsrNanoEncoderConfig]]

```python
transformers.FunAsrNanoEncoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, num_mel_bins: int = 80, hidden_size: int = 512, num_attention_heads: int = 4, intermediate_size: int = 2048, num_hidden_layers: int = 70, hidden_dropout: float = 0.1, attention_dropout: float = 0.1, layer_norm_eps: float = 1e-05, hidden_act: str = 'relu', max_position_embeddings: int = 2049, num_stacked_frames: int = 7, num_timestamp_prediction_layers: int = 20, fsmn_kernel_size: int = 11)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/configuration_fun_asr_nano.py#L25)

**参数：**

num_mel_bins (`int`，*可选*，默认为 `80`)：每个输入帧使用的 mel 特征数量。应与 `AutoFeatureExtractor` 类中使用的值相对应。

hidden_size (`int`，*可选*，默认为 `512`)：隐藏表示的维度。

num_attention_heads (`int`，*可选*，默认为 `4`)：Transformer 解码器中每个注意力层的注意力头数量。

intermediate_size (`int`，*可选*，默认为 `2048`)：MLP 表示的维度。

num_hidden_layers (`int`，*可选*，默认值为 70)：编码器的总层数，包括转录层和后续的预测时间戳层。

hidden_dropout (`float`, *可选*，默认为 `0.1`)：嵌入层、编码器和池化层中所有全连接层的 dropout 概率。

attention_dropout (`float`, *可选*, 默认为 `0.1`) : 注意力概率的 dropout 比率。

layer_norm_eps (`float`，*可选*，默认为 `1e-05`)：层归一化层所使用的 epsilon。

hidden_act (`str`，*可选*，默认为 `relu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

max_position_embeddings (`int`，*可选*，默认为 `2049`)：该模型可能使用的最大序列长度。

num_stacked_frames (`int`，*可选*，默认为 7)：低帧率特征提取所堆叠的连续 mel 帧数量。

num_timestamp_prediction_layers (`int`, *可选*，默认为 20) : 专门用于时间戳预测的编码器层数（最后几层）。转录输出取自第 `num_hidden_layers - num_timestamp_prediction_layers - 1` 层之后。

fsmn_kernel_size (`int`, *可选*，默认为 11)：前馈循环记忆网络（FSMN）卷积的核大小。

这是用于存储 FunAsrNanoModel 配置的类。它根据指定的参数实例化 Fun Asr Nano 模型，并定义模型架构。使用默认值实例化配置将生成与 [FunAudioLLM/Fun-ASR-Nano-2512-hf](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512-hf) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## FunAsrNanoAdaptorConfig[[transformers.FunAsrNanoAdaptorConfig]]

#### transformers.FunAsrNanoAdaptorConfig[[transformers.FunAsrNanoAdaptorConfig]]

```python
transformers.FunAsrNanoAdaptorConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 1024, num_attention_heads: int = 8, intermediate_size: int = 256, num_hidden_layers: int = 2, hidden_dropout: float = 0.0, attention_dropout: float = 0.0, layer_norm_eps: float = 1e-05, hidden_act: str = 'relu', projector_hidden_act: str = 'relu', projector_hidden_size: int = 2048)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/configuration_fun_asr_nano.py#L62)

**参数：**

hidden_size (`int`，*可选*，默认为 `1024`)：隐藏表示的维度。

num_attention_heads (`int`，*可选*，默认为 `8`)：Transformer 解码器中每个注意力层的注意力头数量。

intermediate_size (`int`，*可选*，默认为 `256`)：MLP 表示的维度。

num_hidden_layers (`int`，*可选*，默认为 `2`)：Transformer 解码器中的隐藏层数。

hidden_dropout (`float`, *可选*，默认为 `0.0`)：嵌入层、编码器和池化层中所有全连接层的 dropout 概率。

attention_dropout (`float`, *可选*, 默认为 `0.0`) : 注意力概率的 dropout 比率。

layer_norm_eps (`float`，*可选*，默认为 `1e-05`)：层归一化层所使用的 epsilon。

hidden_act (`str`，*可选*，默认为 `relu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

projector_hidden_act (`str`，*可选*，默认为 `relu`)：多模态投影器使用的激活函数。

projector_hidden_size (`int`，*可选*，默认为 `2048`)：文本和视觉投影层的维度。

这是用于存储 FunAsrNanoModel 配置的类。它根据指定的参数实例化 Fun Asr Nano 模型，并定义模型架构。使用默认值实例化配置将生成与 [FunAudioLLM/Fun-ASR-Nano-2512-hf](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-2512-hf) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## FunAsrNanoFeatureExtractor[[transformers.FunAsrNanoFeatureExtractor]]

#### transformers.FunAsrNanoFeatureExtractor[[transformers.FunAsrNanoFeatureExtractor]]

```python
transformers.FunAsrNanoFeatureExtractor(feature_size: int = 80, sampling_rate: int = 16000, frame_length: int = 25, frame_shift: int = 10, num_frames_lfr: int = 7, stride_lfr: int = 6, window: str = 'hamming', padding_value: float = 0.0, return_attention_mask: bool = True, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/feature_extraction_fun_asr_nano.py#L33)

**参数：**

feature_size (`int`，*可选*，默认为 80)：梅尔频率分箱的数量。

sampling_rate (`int`，*可选*，默认为 16000)：音频的采样率。

frame_length (`int`, *可选*, 默认为 25) : STFT 的帧长（以毫秒为单位）。

frame_shift (`int`, *可选*，默认为 10) : STFT 的帧移（跳长），单位为毫秒。

num_frames_lfr (`int`，*可选*，默认为 7)：要堆叠的连续帧数（LFR 堆叠因子）。

stride_lfr (`int`, *可选*, 默认为 6) : LFR 的降采样步长（每隔 `stride_lfr` 个堆叠帧取一个）。

window (`str`, *可选*, 默认为 `"hamming"`) : STFT 的窗口函数。

padding_value (`float`, *可选*, 默认值为 0.0) : 用于填充较短序列的值。

return_attention_mask (`bool`, *可选*, 默认为 `True`) : 是否返回注意力掩码。

构建 Fun-ASR-Nano 特征提取器。

此特征提取器继承自 [SequenceFeatureExtractor](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)，后者包含了大部分主要方法。有关这些方法的更多信息，请参阅该父类。

它提取与 Kaldi 兼容的 mel 滤波器组特征（通过 `torchaudio.compliance.kaldi.fbank`，与原始 FunASR 前端保持一致），然后应用低帧率（LFR）处理，即堆叠 `num_frames_lfr` 个连续帧，并以步长 `stride_lfr` 进行下采样。

示例：

```python
>>> import numpy as np
>>> from transformers import FunAsrNanoFeatureExtractor

>>> feature_extractor = FunAsrNanoFeatureExtractor()
>>> audio = np.random.randn(16000)  # 1 second of audio at 16kHz
>>> features = feature_extractor(audio, sampling_rate=16000, return_tensors="pt")
>>> features.input_features.shape  # (1, num_frames_after_lfr, 560)
```

#### __调用__[[transformers.FunAsrNanoFeatureExtractor.__call__]]

```python
__call__(raw_speech: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']], sampling_rate: int | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = 'pt', padding: bool | str = True, max_length: int | None = None, truncation: bool = False, pad_to_multiple_of: int | None = None, return_attention_mask: bool | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/feature_extraction_fun_asr_nano.py#L146)

**参数：**

raw_speech (`np.ndarray`、`list[float]`、`list[np.ndarray]`、`list[list[float]]`)：要提取特征的序列或批次的单声道波形。

sampling_rate (`int`, *可选*) : 输入音频的采样率。必须与 `self.sampling_rate` (16000 Hz) 匹配。

return_tensors (`str` 或 [TensorType](/docs/transformers/main/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，则返回指定框架（`"pt"`、`"np"` 等）的张量。

padding (`bool` 或 `str`，*可选*，默认为 `True`)：传递给 [pad()](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad) 的填充策略。

max_length (`int`, *可选*) : 用于填充/截断的最大 LFR 序列长度。

truncation (`bool`，*可选*，默认为 `False`)：是否截断长度超过 `max_length` 的序列。

pad_to_multiple_of (`int`, *可选*) : 如果设置，则将 LFR 序列长度填充为该值的倍数。

return_attention_mask (`bool`, *可选*) : 是否返回 `input_features_mask`。默认为 `self.return_attention_mask`。

**返回值：**

形状为 `(batch, max_lfr_frames, feature_size * num_frames_lfr)` 的 `input_features` 以及帧级别的 `input_features_mask` 的 [BatchFeature](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.BatchFeature)。

从一个或多个原始音频波形中提取 Kaldi mel 滤波器组 + LFR 特征。

## FunAsrNanoProcessor[[transformers.FunAsrNanoProcessor]]

#### transformers.FunAsrNanoProcessor[[transformers.FunAsrNanoProcessor]]

```python
transformers.FunAsrNanoProcessor(feature_extractor, tokenizer, chat_template = None, audio_token = '<|object_ref_start|>')
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/processing_fun_asr_nano.py#L47)

**参数：**

feature_extractor (`FunAsrNanoFeatureExtractor`)：特征提取器是必需的输入。

tokenizer (`Qwen2Tokenizer`)：分词器是必需的输入。

chat_template (`str`) : 一个 Jinja 模板，用于将聊天中的消息列表转换为可分词的字符串。

audio_token (`str`，*可选*，默认为 `"<|object_ref_start|>"`)：在文本中用作音频占位符的标记。

构造一个 FunAsrNanoProcessor，它将特征提取器和分词器封装为单个处理器。

[FunAsrNanoProcessor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoProcessor) 提供了 [FunAsrNanoFeatureExtractor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor) 和 [Qwen2Tokenizer](/docs/transformers/main/zh/model_doc/qwen2#transformers.Qwen2Tokenizer) 的所有功能。有关更多信息，请参阅 [~FunAsrNanoFeatureExtractor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor) 和 [~Qwen2Tokenizer](/docs/transformers/main/zh/model_doc/qwen2#transformers.Qwen2Tokenizer)。

#### __调用__[[transformers.FunAsrNanoProcessor.__call__]]

```python
__call__(text: str | list[str], audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None, output_labels: bool | None = False, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/processing_fun_asr_nano.py#L69)

**参数：**

text (`Union[str, list[str]]`) : 要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果传入预分词输入，请设置 `is_split_into_words=True` 以避免与批量输入产生歧义。

audio (`Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]]`，*可选*)：要准备处理的音频或音频批次。每个音频可以是 NumPy 数组或 PyTorch 张量。对于 NumPy 数组/PyTorch 张量，每个音频的形状应为 (C, T)，其中 C 是通道数，T 是音频的采样长度。

output_labels (`bool`, *可选*, 默认值=False) : 是否返回用于训练的标签。

return_mm_token_type_ids (`bool`, *kwargs*) : 是否返回多模态 token 类型 ID，以指示多模态占位符 token 的位置。

return_text_replacement_offsets (`bool`, *kwargs*) : 是否返回每个多模态占位符及其替换项的字符偏移量。

return_tensors (`str` 或 [TensorType](/docs/transformers/main/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessingKwargs), *可选*) : 针对每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

**返回：** [BatchFeature](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.BatchFeature)

一个包含分词文本（`input_ids`、`attention_mask`）和音频特征（`input_features`、`input_features_mask`）的字典。

#### apply_transcription_request[[transformers.FunAsrNanoProcessor.apply_transcription_request]]

```python
apply_transcription_request(audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], list[typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']]]], language: str | list[str] | None = None, prompt: str | list[str] | None = None, keywords: str | list[str] | list[list[str]] | None = None, transcription: str | list[str] | None = None, tokenize: bool = True, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/processing_fun_asr_nano.py#L134)

**参数：**

audio (`AudioInput` 或 `list[AudioInput]`)：要转录的音频。可以是 URL、本地路径、NumPy 数组、PyTorch 张量，或这些类型的列表。

language (`str` 或 `list[str]`，*可选*) : 目标语言。接受中文、英文或日文的完整英文名称、ISO 代码（`"zh"`、`"en"`、`"ja"`）或检查点的中文语言名称（`"中文"`、`"英文"`、`"日文"`）。单个值会广播到整个批次。

prompt (`str` 或 `list[str]`，*可选*)：可能有助于提升转录效果的上下文信息。列表的长度必须与音频批次大小相匹配。

keywords (`str`、`list[str]` 或 `list[list[str]]`，*可选*)：用于偏向识别的热词。字符串或扁平列表在整个批次中共享；嵌套列表则为每个音频样本提供各自的热词。

transcription (`str` 或 `list[str]`，*可选*)：用于训练的目标转录文本，每个音频对应一个。提供时，每个转录文本将作为助手轮次写入，并返回 `labels`（参见 [__call__()](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoProcessor.__call__) 中的 `output_labels`）。

tokenize (`bool`，*可选*，默认为 `True`)：是否对提示词进行分词并处理音频。如果为 `False`，则不会加载音频，提示词将以字符串形式返回，其中包含未展开的音频占位符。将它们与音频一起传递给处理器，`processor(text=prompts, audio=audio)`，将得到与 `tokenize=True` 相同的输出。

- ****kwargs** : 转发给 [apply_chat_template()](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessorMixin.apply_chat_template) 的额外关键字参数。处理器参数（例如 `text_kwargs`、`audio_kwargs` 等）应通过 `processor_kwargs={...}` 传递。

**返回：** [BatchFeature](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.BatchFeature) 或 `list[str]`

当 `tokenize=False` 时，每个音频对应一个提示；否则，处理器会输出可直接传递给 [FunAsrNanoForConditionalGeneration.generate()](/docs/transformers/main/zh/main_classes/text_generation#transformers.GenerationMixin.generate) 的结果，或在给定 `transcription` 时传递给 [FunAsrNanoForConditionalGeneration.forward()](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoForConditionalGeneration.forward) 以计算损失。

使用检查点的结构化转录聊天模板为 ASR 准备输入，用于推理，或在给定 `transcription` 时用于训练。

## FunAsrNanoEncoder[[transformers.FunAsrNanoEncoder]]

#### transformers.FunAsrNanoEncoder[[transformers.FunAsrNanoEncoder]]

```python
transformers.FunAsrNanoEncoder(config: FunAsrNanoEncoderConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/modeling_fun_asr_nano.py#L279)

**参数：**

config ([FunAsrNanoEncoderConfig](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoEncoderConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

Fun-ASR-Nano 音频编码器（SenseVoice SAN-M 架构），顶部未添加任何 head。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.FunAsrNanoEncoder.forward]]

```python
forward(input_features: Tensor, input_features_mask: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/modeling_fun_asr_nano.py#L313)

**参数：**

input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`)：与输入音频特征对应的张量。可以使用 [FunAsrNanoFeatureExtractor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor) 获取音频特征。有关详细信息，请参阅 [FunAsrNanoFeatureExtractor.__call__()](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor.__call__)（[FunAsrNanoProcessor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoProcessor) 使用 [FunAsrNanoFeatureExtractor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor) 处理音频）。

input_features_mask (`torch.LongTensor`，形状为 `(batch_size, padded_feature_length)`)：有效 mel 帧为 1，填充部分为 0。

**返回：** [BaseModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutput) 或 `tuple(torch.Tensor)`

一个 [BaseModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[FunAsrNanoConfig](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoConfig)）和输入。

[FunAsrNanoEncoder](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoEncoder) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

## FunAsrNanoModel[[transformers.FunAsrNanoModel]]

#### transformers.FunAsrNanoModel[[transformers.FunAsrNanoModel]]

```python
transformers.FunAsrNanoModel(config: FunAsrNanoConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/modeling_fun_asr_nano.py#L393)

**参数：**

config ([FunAsrNanoConfig](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

Fun-ASR-Nano 模型（SenseVoice SAN-M 音频编码器、一个 Transformer 适配器以及一个 Qwen3 语言模型），不包含语言建模头。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.FunAsrNanoModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/modeling_fun_asr_nano.py#L468)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [FunAsrNanoFeatureExtractor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor) 获取音频特征。有关详细信息，请参阅 [FunAsrNanoFeatureExtractor.__call__()](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor.__call__)（[FunAsrNanoProcessor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoProcessor) 使用 [FunAsrNanoFeatureExtractor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor) 处理音频）。

input_features_mask (`torch.Tensor`，形状为 `(batch_size, feature_sequence_length)`)：用于避免对填充特征索引执行注意力机制的掩码。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

**返回：** `FunAsrNanoModelOutputWithPast` 或 `tuple(torch.Tensor)`

`FunAsrNanoModelOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[FunAsrNanoConfig](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoConfig)）和输入。

[FunAsrNanoModel](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **audio_hidden_states** (`torch.Tensor`，*可选*) -- 投影后的音频隐藏状态。

## FunAsrNanoForConditionalGeneration[[transformers.FunAsrNanoForConditionalGeneration]]

#### transformers.FunAsrNanoForConditionalGeneration[[transformers.FunAsrNanoForConditionalGeneration]]

```python
transformers.FunAsrNanoForConditionalGeneration(config: FunAsrNanoConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/modeling_fun_asr_nano.py#L551)

**参数：**

config ([FunAsrNanoConfig](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

用于语音识别的 Fun-ASR-Nano 模型：一个 SenseVoice SAN-M 音频编码器、一个 Transformer 适配器，以及一个带有语言建模头的 Qwen3 语言模型。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.FunAsrNanoForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/fun_asr_nano/modeling_fun_asr_nano.py#L564)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [FunAsrNanoFeatureExtractor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor) 获取音频特征。有关详细信息，请参阅 [FunAsrNanoFeatureExtractor.__call__()](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor.__call__)（[FunAsrNanoProcessor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoProcessor) 使用 [FunAsrNanoFeatureExtractor](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoFeatureExtractor) 处理音频）。

input_features_mask (`torch.Tensor`，形状为 `(batch_size, feature_sequence_length)`)：用于避免对填充特征索引执行注意力机制的掩码。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于计算掩码语言建模损失的标签。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

logits_to_keep (`Union[int, torch.Tensor]`，*可选*，默认为 `0`)：如果为 `int`，则计算最后 `logits_to_keep` 个 token 的 logits。如果为 `0`，则计算所有 `input_ids` 的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当可观。如果为 `torch.Tensor`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。

**返回：** `FunAsrNanoCausalLMOutputWithPast` 或 `tuple(torch.Tensor)`

`FunAsrNanoCausalLMOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[FunAsrNanoConfig](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoConfig)）和输入。

[FunAsrNanoForConditionalGeneration](/docs/transformers/main/zh/model_doc/fun_asr_nano#transformers.FunAsrNanoForConditionalGeneration) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例。
- **hidden_states** (`tuple[torch.Tensor]`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple[torch.Tensor]`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。
- **audio_hidden_states** (`torch.Tensor`，*可选*) -- 音频编码器投影后的隐藏状态。

示例：

```python
>>> from transformers import FunAsrNanoForConditionalGeneration, AutoProcessor

>>> model_id = "FunAudioLLM/Fun-ASR-Nano-2512-hf"
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> model = FunAsrNanoForConditionalGeneration.from_pretrained(model_id, device_map="auto")
```