CGXBeta

推理API参考

- 分钟等级: 进阶

DeepSeek-V3提供了一个高性能推理API,专为利用模型的先进混合专家(MoE)架构进行高效文本生成而设计。本参考指南解释了推理API的核心组件、它们的功能以及如何有效地利用它们进行基本和高级用例。

核心API组件

DeepSeek-V3的推理API由几个关键组件组成,共同提供高效的文本生成:

组件描述关键文件
模型定义包含MoE和MLA的核心模型架构model.py
文本生成令牌采样和生成逻辑generate.py
权重转换用于在不同模型格式之间转换的工具convert.py
精度处理FP8到BF16转换工具fp8_cast_bf16.py
配置不同尺寸的模型参数configs/*.json

来源:model.py, generate.py

模型配置

DeepSeek-V3使用ModelArgs数据类来定义模型配置。下表显示了关键参数:

参数描述示例值(671B模型)
vocab_size词汇表大小129280
dim模型维度7168
n_layers变换器层数61
n_heads注意力头数128
n_routed_expertsMoE中的路由专家数256
n_activated_experts每个令牌激活的专家数8
dtype计算数据类型("fp8""bf16""fp8"

加载模型配置:

PYTHON
import json
from model import ModelArgs
 
# 从文件加载配置
with open("configs/config_671B.json") as f:
    args = ModelArgs(**json.load(f))

来源:model.py#L19-L84, configs/config_671B.json

初始化模型

model.py中的Transformer类是推理API的主要入口点。它使用提供的配置初始化模型:

PYTHON
import torch
from model import Transformer, ModelArgs
 
# 根据配置将默认数据类型设置为bfloat16或float8_e4m3fn
torch.set_default_dtype(torch.bfloat16)  # 或torch.float8_e4m3fn用于FP8
 
# 初始化模型
with torch.device("cuda"):
    model = Transformer(args)

来源:model.py#L735-L767, generate.py#L115-L117

加载模型权重

DeepSeek-V3使用safetensors加载模型权重。在将模型用于推理之前,需要加载预训练权重:

PYTHON
from safetensors.torch import load_model
import os
 
# 加载模型权重
load_model(model, os.path.join(ckpt_path, f"model{rank}-mp{world_size}.safetensors"))

在使用分布式推理时,权重会跨设备分割,并根据排名和世界大小加载。

来源:generate.py#L119

文本生成API

单令牌生成

Transformer类的forward方法用于单令牌生成。它接受令牌ID作为输入,返回下一个令牌的logits:

PYTHON
@torch.inference_mode()
def forward(self, tokens: torch.Tensor, start_pos: int = 0):
    """
    Transformer模型的正向传递。
 
    Args:
        tokens (torch.Tensor): 形状为(batch_size, seq_len)的令牌ID输入张量。
        start_pos (int, optional): 序列中的起始位置。默认为0。
 
    Returns:
        torch.Tensor: 下一个令牌预测的logits张量。
    """
    # 实现细节...
    return logits

来源:model.py#L768-L794

多令牌生成

generate.py中的generate函数提供了主要的文本生成功能。它支持基于温度的采样,并处理生成直到结束序列令牌或最大令牌限制达到:

PYTHON
@torch.inference_mode()
def generate(
    model: Transformer,
    prompt_tokens: List[List[int]],
    max_new_tokens: int,
    eos_id: int,
    temperature: float = 1.0
) -> List[List[int]]:
    """
    基于给定的提示令牌生成新令牌。
 
    Args:
        model (Transformer): 用于令牌生成的变换器模型。
        prompt_tokens (List[List[int]]): 包含提示令牌的列表。
        max_new_tokens (int): 要生成的最大新令牌数。
        eos_id (int): 结束序列令牌ID。
        temperature (float): 采样温度(1.0=标准,<1.0=更窄,>1.0=更宽)。
 
    Returns:
        List[List[int]]: 包含生成令牌的列表。
    """
    # 实现细节...
    return completion_tokens

来源:generate.py#L30-L78

聊天界面

API提供了一个便捷的聊天界面,处理消息历史并应用适当的聊天模板:

PYTHON
from transformers import AutoTokenizer
 
tokenizer = AutoTokenizer.from_pretrained(ckpt_path)
 
# 初始化消息历史
messages = []
 
# 添加用户消息
messages.append({"role": "user", "content": "Tell me about DeepSeek-V3"})
 
# 应用聊天模板并生成响应
prompt_tokens = tokenizer.apply_chat_template(messages, add_generation_prompt=True)
completion_tokens = generate(model, [prompt_tokens], max_new_tokens, 
                            tokenizer.eos_token_id, temperature)
completion = tokenizer.decode(completion_tokens[0], skip_special_tokens=True)
 
# 将助手响应添加到消息历史
messages.append({"role": "assistant", "content": completion})

来源:generate.py#L122-L144

批处理

处理多个提示的批处理:

PYTHON
# 从文件读取多个提示
with open(input_file) as f:
    prompts = [line.strip() for line in f.readlines()]
 
# 编码所有提示
prompt_tokens = [tokenizer.apply_chat_template([{"role": "user", "content": prompt}], 
                add_generation_prompt=True) for prompt in prompts]
 
# 为所有提示生成补全
completion_tokens = generate(model, prompt_tokens, max_new_tokens, 
                            tokenizer.eos_token_id, temperature)
completions = tokenizer.batch_decode(completion_tokens, skip_special_tokens=True)

来源:generate.py#L146-L155

分布式推理

DeepSeek-V3支持使用PyTorch的分布式功能跨多个GPU进行分布式推理。推理API自动处理张量并行操作:

PYTHON
import torch.distributed as dist
 
# 初始化分布式环境
world_size = int(os.getenv("WORLD_SIZE", "1"))
rank = int(os.getenv("RANK", "0"))
local_rank = int(os.getenv("LOCAL_RANK", "0"))
 
if world_size > 1:
    dist.init_process_group("nccl")
    torch.cuda.set_device(local_rank)
 
# 使用torchrun启动分布式推理
# torchrun --nnodes 2 --nproc-per-node 8 --node-rank $RANK --master-addr $ADDR generate.py 
#   --ckpt-path /path/to/model --config configs/config_671B.json --interactive

来源:generate.py#L100-L108, model.py#L754-L756

精度模式

DeepSeek-V3支持两种精度模式:FP8(原生)和BF16。默认模式由配置确定。

使用FP8精度

PYTHON
# 在配置中将FP8设置为模型的数据类型
args = ModelArgs(dtype="fp8", ...)
 
# 模型将内部使用torch.float8_e4m3fn
model = Transformer(args)

将FP8转换为BF16

对于不支持FP8的框架,可以将模型权重转换为BF16:

PYTHON
# 从命令行:
python fp8_cast_bf16.py --input-fp8-hf-path /path/to/fp8_weights --output-bf16-hf-path /path/to/bf16_weights

来源:README.md#L243-L247, model.py#L757

权重结构

DeepSeek-V3权重按特定结构组织:

  1. 主模型权重:671B参数(每令牌激活36.7B)

    • 嵌入层
    • 61个变换器层
    • 输出归一化和投影
  2. 多令牌预测(MTP)模块:14B附加参数

    • 与主模型共享嵌入
    • 用于推测解码的特殊层

convert.py工具帮助重新组织这些权重以进行高效部署:

PYTHON
python convert.py --hf-ckpt-path /path/to/DeepSeek-V3 --save-path /path/to/DeepSeek-V3-Demo --n-experts 256 --model-parallel 16

来源:README_WEIGHTS.md#L11-L48, convert.py#L33-L45

CLI参数

generate.py脚本提供了一个命令行界面,具有以下参数:

参数描述默认值
--ckpt-path模型检查点目录路径必需
--config配置文件路径必需
--input-file包含输入提示的文件路径,用于批处理""
--interactive启用聊天交互模式False
--max-new-tokens要生成的最大新令牌数200
--temperature采样温度0.2

示例用法:

BASH
# 交互模式
torchrun --nnodes 2 --nproc-per-node 8 --node-rank $RANK --master-addr $ADDR \
  generate.py --ckpt-path /path/to/model --config configs/config_671B.json \
  --interactive --temperature 0.7 --max-new-tokens 200
 
# 批处理
torchrun --nnodes 2 --nproc-per-node 8 --node-rank $RANK --master-addr $ADDR \
  generate.py --ckpt-path /path/to/model --config configs/config_671B.json \
  --input-file input.txt --temperature 0.7

来源:generate.py#L176-L184, README.md#L295-L303

高级功能

自定义线性层实现

DeepSeek-V3实现了专门的线性层,以处理不同的精度格式和分布式操作:

  • Linear:支持量化权重的基本线性层
  • ColumnParallelLinear:具有列并行性的线性层
  • RowParallelLinear:具有行并行性的线性层

这些实现优化了分布式推理场景的性能。

来源:model.py#L164-L264

自定义注意力实现

多头潜在注意力(MLA)模块提供了两种注意力实现:

  1. naive:具有单独的键和值缓存的标准注意力
  2. absorb:优化的注意力,具有组合的KV缓存和因式分解计算

可以通过model.py中的全局变量attn_impl选择实现。

来源:model.py#L393-L494

与其他框架的集成

DeepSeek-V3可以使用各种开源框架进行部署:

  1. SGLang:支持在NVIDIA和AMD GPU上进行BF16和FP8推理
  2. LMDeploy:支持高效FP8和BF16推理用于部署
  3. TensorRT-LLM:支持BF16推理,带INT4/8量化
  4. vLLM:支持DeepSeek-V3的FP8和BF16精度
  5. LightLLM:支持单节点或多节点部署

每个框架可能需要特定的集成代码,这不包括在核心推理API中。