接口功能

此接口调用mindie-llm的采样器，对推理输出的logitis进行后处理。

此方法根据后处理参数从输入对数几率中进行采样，并选择词元ID。使用SamplingMetadata类，还是使用即将日落的SamplingData类和SamplingParam类组合，取决于参数sampling_metadata的类型。即将日落的SamplingData类和SamplingParam类组合不支持best_of函数和logprobs函数。

返回值：

Union [SamplingOutput, Tuple [np.ndarray, Optional [np.ndarray]]]：当传入SamplingMetadata对象时，将返回SamplingOutput的实例；否则将返回一个包含词元ID和对数几率的元组。

接口实现

def sample(
        self,
        logits: Any,
        sampling_metadata: Optional[Union[SamplingMetadata, SamplingData]] = None,
        sampling_param: Optional[SamplingParam] = None,
        **kwargs
        
    ) -> Tuple[np.ndarray, Optional[np.ndarray]]:
        sampling_data = None
        if isinstance(sampling_metadata, SamplingData):
            sampling_data = sampling_metadata
        elif 'sampling_data' in kwargs:
            sampling_data = kwargs.get('sampling_data')
        if sampling_data is not None:  # Enter deprecated branch
            sampling_metadata = SamplingMetadata.from_deprecated(sampling_data, sampling_param)
            output = self.sampler(logits, sampling_metadata)
            output = (output.token_ids, output.logprobs)
        else:
            output = self.sampler(logits, sampling_metadata)
        return output
        

参数说明

参数名称	是否必选	类型	默认值	描述
logits	是	Any	-	对应后端类型的Tensor，当前支持torch.Tensor或mindspore.Tensor。未经过softmax函数处理的网络输出结果，通常表示每个类别的得分或概率。
sampling_metadata	否	Union[SamplingMetadata, SamplingData]	None	可以是SamplingMetadata或SamplingData的实例。SamplingMetadata包含所有采样参数，如惩罚系数、温度、top_k、top_p、输入和输出词元ID等。SamplingData仅包含请求ID、预填充标志、输入词元ID和输出词元ID。说明： SamplingData即将日落，仅用于接口的前向兼容，不推荐优先使用。
sampling_param	否	SamplingParam	None	即将日落的入参，仅用于和SamplingData搭配传入，默认为None。SamplingParam类实例，用于传入batch后处理参数。通过SamplingParam类方法，SamplingParam.from_numpy可以创建类实例sampling_param。
**kwargs	否	SamplingData	-	兼容即将日落的SamplingData类，允许使用关键词sampling_data传入SamplingData类实例。

补充说明

sampling_metadata通过SamplingMetadata.from_numpy（类方法）进行构造。

文件路径：“mindie_llm/text_generator/utils/sampling_metadata.py”

表1 SamplingMetadata.from_numpy接口参数说明
参数名称	是否必选	类型	默认值	描述
batch_sequence_ids	是	List[np.ndarray]	-	包含numpy数组的列表。每个numpy数组表示每个请求包含的序列ID，每个请求允许包含多个序列ID，其数量等于best_of参数指定的数量。
reserved_sequence_ids	否	List[np.ndarray]	None	包含numpy数组的列表。用于生成多候选token预留的序列ID，该列表的元素数量与请求数一致。每个请求预留的序列ID数量： beam search场景：n-1 多采样场景：best_of - 1
is_prefill	否	bool	True	用于判断是否在生成首token。
repetition_penalty	否	np.ndarray	None	一维float数组，对应批处理中每个请求的重复惩罚。
frequency_penalty	否	np.ndarray	None	一维float数组，对应批处理中每个请求的频率惩罚。
presence_penalty	否	np.ndarray	None	一维float数组，对应批处理中每个请求的存在惩罚。
temperature	否	np.ndarray	None	一维float数组，对应批处理中每个请求的温度。
top_k	否	np.ndarray	None	一维int数组，对应批处理中每个请求在采样时依次从最高概率选项中选择的数量。
top_p	否	np.ndarray	None	一维float数组，对应批处理中每个请求在采样时的累加概率阈值。
do_sample	否	np.ndarray	None	一维bool数组，对应批处理中每个请求是否做采样。
top_logprobs	否	np.ndarray	None	一维int数组，对应批处理中每个请求需要返回最大多少个对数概率值。需要注意top_logprobs至少为1的请求才会返回被选中token的logprobs。在需要被选中token的logprobs而不需要top_logprobs的情况下，请将top_logprobs对应请求的值改为1，将0记录在num_top_tokens参数中。
seeds	否	np.ndarray	None	一维int数组，对应批处理中每个请求在采样时的随机种子。
num_top_tokens	否	np.ndarray	None	一维int数组，仅用于记录top_logprobs的原始值，不影响计算过程。
n	否	np.ndarray	None	一维int数组，表示每个序列生成多个候选词元的数量，默认为1，其值应小于等于best_of。
best_of	否	np.ndarray	None	一维int数组，表示每个序列使用多采样方法得到候选词元的数量，默认为1，即不开启多采样。
use_beam_search	否	np.ndarray	None	一维bool数组，表示每个序列是否需要使用束搜索。
to_tensor	否	callable	None	to_tensor方法，用于将np.ndarray生成不同后端的张量。若传入的all_input_ids或output_ids不为None，则本项必选。
all_sequence_ids	否	np.ndarray	None	batch_sequence_ids拼接后的所有序列id，会自动计算，不建议传入。

在构造sampling_metadata实例后：

若要使用repetition_penalty，则需要调用sampling_metadata.update_token_ids（实例方法）刷新all_token_ids。
若要使用frequency_penalty或presence_penalty，则需要调用sampling_metadata.update_token_ids（实例方法）刷新output_token_ids。

文件路径：“mindie_llm/text_generator/utils/sampling_metadata.py”

表2 SamplingMetadata.update_token_ids接口参数说明
参数名称	是否必选	类型	默认值	描述
all_token_ids	否	np.ndarray	None	二维int数组，包含每个请求所有输入加输出的token id。用于repetition_penalty计算。
output_token_ids	否	np.ndarray	None	二维int数组，包含每个请求所有输出的token id。用于frequency_penalty和presence_penalty计算。

sampling_data通过SamplingData.from_numpy进行构造。

文件路径：“mindie_llm/text_generator/utils/sampling_metadata.py”。

表3 SamplingData.from_numpy接口参数说明
参数名称	是否必选	类型	默认值	描述
all_input_ids	否	np.ndarray	None	二维int数组，包含每个请求所有输入加输出的token id。用于repetition_penalty计算。
output_ids	否	np.ndarray	None	二维int数组，包含每个请求所有输出的token id。用于frequency_penalty和presence_penalty计算。
to_tensor	否	callable	None	to_tensor方法，用于将np.ndarray生成不同后端的张量。若传入的all_input_ids或output_ids不为None，则本项必选。
is_prefill	否	bool	True	用于判断是否在生成第一个token。本项与request_ids成对传入，可触发缓存机制，提升性能。
request_ids	否	np.ndarray	None	一维int数组，批处理中所有请求的唯一标识。本项与is_prefill成对传入，可触发缓存机制，提升性能。

sampling_param通过SamplingParam.from_numpy进行构造。

文件路径：“mindie_llm/text_generator/utils/sampling_metadata.py”。

表4 SamplingParam.from_numpy接口参数说明
参数名称	是否必选	类型	默认值	描述
repetition_penalty	否	np.ndarray	None	一维float数组，对应批处理中每个请求的重复惩罚。
frequency_penalty	否	np.ndarray	None	一维float数组，对应批处理中每个请求的频率惩罚。
presence_penalty	否	np.ndarray	None	一维float数组，对应批处理中每个请求的存在惩罚。
temperature	否	np.ndarray	None	一维float数组，对应批处理中每个请求的温度。
top_k	否	np.ndarray	None	一维int数组，对应批处理中每个请求在采样时依次从最高概率选项中选择的数量。
top_p	否	np.ndarray	None	一维float数组，对应批处理中每个请求在采样时的累加概率阈值。
seed	否	np.ndarray	None	一维int数组，对应批处理中每个请求在采样时的随机种子。
do_sample	否	np.ndarray	None	一维bool数组，对应批处理中每个请求是否做采样。
to_tensor	否	callable	None	to_tensor方法，用于将np.ndarray生成不同后端的张量。若传入的任意一个参数不为None，则本项必选。

后处理参数数组元素数值说明：

针对单个request而言，目前支持惩罚参数和采样参数两类后处理参数，如表5及表6所示。

表5 惩罚参数
参数名称	类型	取值要求	描述
repetition_penalty	float	> 0，建议不超过2	重复惩罚的参数，对输入输出中已存在的token施加除法级惩罚，1.0表示没有惩罚。
frequency_penalty	float	负数表示奖励，建议 > 0	频率惩罚，根据输出中已存在的token的出现频率施加减法级惩罚，0.0表示没有惩罚。
presence_penalty	float	负数表示奖励，建议 > 0	存在惩罚，对输出中已存在的token施加减法级惩罚，0.0表示没有惩罚。

若模型路径下的config.json和generate_config.json中都没有配置pad_token_id时，需要手动添加pad_token_id。

可配置范围：[-1, vocab_size]，建议值：vocab_size。

表6 采样参数
参数名称	类型	取值要求	描述
temperature	float	> 0，建议不超过2	控制生成文本的随机性，值越高文本越随机。
top_k	int	0 < top_k < 词表长度	限制每次生成时候概率最高的k个数量。
top_p	float	0.0 < top_p <= 1.0	选择概率总和达到p的所有选项，用于控制生成的多样性。
seed	int	>= 0	设置随机数种子，以确保结果的可重复性。
do_sample	bool	布尔值	决定是否使用抽样策略生成文本，而非选择概率最高的选项。设置为“False”时，若存在采样参数，则自动变为“True”。

sample接口

接口功能

接口实现

参数说明

补充说明