ApX 标志ApX 标志

趋近智

REST API 文档

显存计算器 API

将大语言模型需求规划以编程式集成到您的仪表盘、CI/CD 工作流或自定义部署脚本中。

获取 API 密钥MCP 服务器文档

API 参考

身份验证

计算需要包含设置中创建的 API 令牌。请在请求头中将其作为 Bearer 凭据传递。

Authorization: Bearer YOUR_API_KEY_HERE
生成令牌
POST
/api/v1/vram-calculation/inference

计算大语言模型推理工作负载所需的 GPU 显存分配详情及性能指标。

请求 JSON Body 参数：推理

字段类型描述与枚举选项

核心模型与硬件参数

gpu_key *stringGPU 配置密钥，如 rtx_4090 或 h100_80。完整列表请参阅 GET /gpus。
llm_key *string模型变体标识符，如 llama-3-8b-instruct 或 custom。完整列表请参阅 GET /llms。
quantizationstring权重量化目标。可选值：fp32，fp16，fp8，int8，int4，q8，q4_k_m 等。默认为 fp16。
custom_vramnumber自定义 GPU 显存容量，单位为 GB。如果 gpu_key 为 custom_discrete 或 custom_apple_silicon，则为必填项。
custom_bandwidthnumber自定义 GPU 内存带宽，单位为 GB/s。如果 gpu_key 为 custom_discrete 或 custom_apple_silicon，则为必填项。
custom_tflopsnumber自定义 GPU FP16 计算算力，单位为 TFLOPS。如果 gpu_key 为 custom_discrete 或 custom_apple_silicon，则为必填项。
framework_presetstring估算所模拟的推理运行时：auto、vllm、tensorrt_llm、llama_cpp、ollama、hf_transformers、diffusers 或 generic。默认为 auto：GGUF 量化时选择 llama_cpp，扩散模型选择 diffusers，否则选择 vllm。generic 复现早期 API 版本与框架无关的估算，仍接受别名 legacy_auto。响应中的 framework_preset 字段给出实际使用的运行时。

语言模型工作负载参数

batch_sizeinteger批次大小。默认为 1。
seq_lengthinteger以 token 为单位的上下文序列长度。默认为 2048。
concurrent_usersinteger并发用户数。默认为 1。
kv_cache_quantizationstringKV 缓存量化精度。可选值：fp16，fp8，int8，int4。默认为 fp16。
enable_prefix_cachingboolean启用 KV 缓存前缀缓存。默认沿用框架预设的行为，在 vllm 和 tensorrt_llm 下默认开启。需 shared_prefix_ratio 大于 0 才生效。
shared_prefix_rationumber共享前缀占提示序列的比例。范围：0.0 到 1.0。默认为 0.0。
enable_continuous_batchingboolean启用连续批处理。默认沿用框架预设的行为。
inference_parallelismstring并行策略。可选值：pipeline，tensor。默认为 pipeline。
vocab_sizeinteger自定义词表大小，例如 Llama 3 的 128256 或 Gemma 的 256000。默认为 32000。
ffn_intermediate_sizeinteger自定义 MLP 或 SwiGLU 中间层维度大小，例如 Llama 3 8B 的 14336。
kv_source_layer_countinteger压缩或混合架构如 CSA2 中生成共享 KV 缓存状态的层数。
kv_latent_diminteger架构如 MLA 或 CSA2 的潜在压缩 KV 缓存维度。
indexer_diminteger架构如 DSA 或 CSA2 的稀疏路由索引键维度。

扩散与 DiT 工作负载参数

image_widthinteger扩散生成的图像宽度像素数。图像模型默认为 1024，视频模型默认为 1280。
image_heightinteger扩散生成的图像高度像素数。图像模型默认为 1024，视频模型默认为 720。
num_framesinteger视频扩散模型生成的总帧数。图像模型默认为 1，视频模型默认为 49。
inference_stepsinteger扩散生成的去噪推理步数。默认为 20。
guidance_scalenumber无分类器引导尺度数值。Schnell 默认为 1.0，Dev 默认为 3.5。
encoder_offloadboolean在去噪步骤中将 T5 或 CLIP 等文本编码器顺序卸载至主机 CPU 内存。默认为 true。
vae_tilingboolean启用空间与时间分块 VAE 解码以限制峰值激活显存占用。图像模型默认为 false，视频模型默认为 true。

分布式硬件与拓扑参数

num_gpusinteger单个节点上配置的 GPU 数量。在未使用集群参数时默认为 1；与 num_nodes 和 gpus_per_node 互斥。
num_nodesinteger集群中物理服务器节点/机架的数量。使用集群配置时必填；与 num_gpus 互斥。
gpus_per_nodeinteger集群中每个服务器节点配置的 GPU 数量。使用集群配置时必填；与 num_gpus 互斥。
tp_degreeinteger用于在多个 GPU 上分割权重分片的张量并行维度。默认为 1。
pp_degreeinteger用于在不同节点或设备间按顺序分配模型层的流水线并行维度。默认为 1。
interconnect_typestring多 GPU 设置的互连类型。支持的值包括 PCIe 类型 pcie3、pcie4、pcie5，NVLink 类型 nvlink_bridge、nvlink_gen2 至 nvlink_gen6，InfiniBand 类型 infiniband_hdr、infiniband_edr，以及以太网类型 ethernet10g 至 ethernet400g。默认为 pcie4。
inter_node_interconnectstring集群中不同节点之间的网络互连连接。例如：ethernet100g, ethernet400g, infiniband_hdr。

主机与存储卸载参数

enable_offloadingboolean启用 GPU 卸载。默认为 false。
offload_targetstring卸载层的存储目标。可选值：cpu_ram，nvme。
num_offload_layersinteger要卸载的模型层数。
percentage_offloadnumber要卸载的层数百分比，范围从 0 到 100。
offload_kv_cacheboolean将 KV 缓存卸载到存储目标。默认为 false。

cURL 示例：推理

Shell 请求

curl -X POST https://apxml.com/api/v1/vram-calculation/inference \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "gpu_key": "rtx_4090",
    "llm_key": "llama-3-8b-instruct",
    "quantization": "q4_k_m",
    "batch_size": 1,
    "seq_length": 2048
  }'

Python 示例：推理

Python 脚本

import requests

url = "https://apxml.com/api/v1/vram-calculation/inference"
headers = {
    "Authorization": "Bearer YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}
payload = {
    "gpu_key": "rtx_4090",
    "llm_key": "llama-3-8b-instruct",
    "quantization": "q4_k_m",
    "batch_size": 1,
    "seq_length": 2048
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

cURL 示例：扩散模型推理

Shell 请求

curl -X POST https://apxml.com/api/v1/vram-calculation/inference \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "gpu_key": "rtx_4090",
    "llm_key": "flux-1-schnell",
    "quantization": "fp16",
    "image_width": 1024,
    "image_height": 1024,
    "encoder_offload": true
  }'

Python 示例：扩散模型推理

Python 脚本

import requests

url = "https://apxml.com/api/v1/vram-calculation/inference"
headers = {
    "Authorization": "Bearer YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}
payload = {
    "gpu_key": "rtx_4090",
    "llm_key": "flux-1-schnell",
    "quantization": "fp16",
    "image_width": 1024,
    "image_height": 1024,
    "encoder_offload": True
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
POST
/api/v1/vram-calculation/finetuning

计算大语言模型微调与训练工作负载所需的 GPU 显存分配详情、优化影响以及数据集训练速度。

请求 JSON Body 参数：微调

字段类型描述与枚举选项
gpu_key *stringGPU 配置密钥，如 rtx_4090 或 h100_80。完整列表请参阅 GET /gpus。
llm_key *string模型变体标识符，如 llama-3-8b-instruct 或 custom。完整列表请参阅 GET /llms。
finetuning_methodstring微调方法。可选值：full，lora，qlora。默认为 lora。
fine_tuning_quantizationstring全量微调的基础模型精度。当方法为 full 时使用。可选值：fp32，fp16，fp8。默认为 fp16。
lora_rankintegerLoRA 秩大小。当方法为 lora 或 qlora 时使用。默认为 16。
gradient_accumulation_stepsinteger梯度累积步数。默认为 1。
batch_sizeinteger全局批次大小。默认为 1。
seq_lengthinteger以 token 为单位的上下文序列长度。默认为 2048。
num_samplesinteger数据集中总样本数。
tokens_per_sampleinteger每样本的平均 token 数。默认为 seq_length。
num_epochsinteger训练周期数。默认为 3。
framework_presetstring估算所模拟的训练框架：auto、hf_trainer、unsloth、torchtune 或 generic。默认为 auto，即选择 hf_trainer。generic 复现早期 API 版本与框架无关的估算，仍接受别名 legacy_auto。响应中的 framework_preset 字段给出实际使用的框架。
optimization_configobject高级优化配置标志。包含布尔标志如 flash_attention，gradient_checkpointing，use_8bit_optimizer，use_paged_optimizer，use_fused_kernels，activation_offloading 等，以及整数 zero_stage。
custom_vramnumber自定义 GPU 显存容量，单位为 GB。如果 gpu_key 为 custom_discrete 或 custom_apple_silicon，则为必填项。
custom_bandwidthnumber自定义 GPU 内存带宽，单位为 GB/s。如果 gpu_key 为 custom_discrete 或 custom_apple_silicon，则为必填项。
custom_tflopsnumber自定义 GPU FP16 计算算力，单位为 TFLOPS。如果 gpu_key 为 custom_discrete 或 custom_apple_silicon，则为必填项。
num_gpusinteger单个节点上配置的 GPU 数量。在未使用集群参数时默认为 1；与 num_nodes 和 gpus_per_node 互斥。
num_nodesinteger集群中物理服务器节点/机架的数量。使用集群配置时必填；与 num_gpus 互斥。
gpus_per_nodeinteger集群中每个服务器节点配置的 GPU 数量。使用集群配置时必填；与 num_gpus 互斥。
enable_offloadingboolean启用卸载到主机系统。默认为 false。
offload_targetstring卸载层的存储目标。可选值：cpu_ram，nvme。
interconnect_typestring多 GPU 设置的互连类型。支持的值包括 PCIe 类型 pcie3、pcie4、pcie5，NVLink 类型 nvlink_bridge、nvlink_gen2 至 nvlink_gen6，InfiniBand 类型 infiniband_hdr、infiniband_edr，以及以太网类型 ethernet10g 至 ethernet400g。默认为 pcie4。
tp_degreeinteger用于在多个 GPU 上分割权重分片的张量并行维度。默认为 1。
pp_degreeinteger用于在不同节点或设备间按顺序分配模型层的流水线并行维度。默认为 1。
inter_node_interconnectstring集群中不同节点之间的网络互连连接。例如：ethernet100g, ethernet400g, infiniband_hdr。

cURL 示例：微调

Shell 请求

curl -X POST https://apxml.com/api/v1/vram-calculation/finetuning \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "gpu_key": "rtx_4090",
    "llm_key": "llama-3-8b-instruct",
    "finetuning_method": "lora",
    "lora_rank": 16,
    "batch_size": 4,
    "seq_length": 2048
  }'

Python 示例：微调

Python 脚本

import requests

url = "https://apxml.com/api/v1/vram-calculation/finetuning"
headers = {
    "Authorization": "Bearer YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}
payload = {
    "gpu_key": "rtx_4090",
    "llm_key": "llama-3-8b-instruct",
    "finetuning_method": "lora",
    "lora_rank": 16,
    "batch_size": 4,
    "seq_length": 2048
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

响应 Body：推理示例

推理输出

{
  "vram_usage": 6.84,
  "vram_percentage": 28.5,
  "actual_vram_percentage": 28.5,
  "memory_status": "okay",
  "static_shared_memory": 5.43,
  "per_user_memory": 0.52,
  "estimated_latency_tps": 45.2,
  "estimated_throughput_tps": 45.2,
  "per_user_tps": 45.2,
  "ms_per_token": 22.1,
  "ttft": 120,
  "ttft_ms": 120,
  "estimated_system_ram_required": 16.0,
  "offloaded_memory": 0.0,
  "estimated_power_draw": 320,
  "memory_details": {
    "Base Model Weights": 5.43,
    "KV Cache": 0.52,
    "Activations": 0.35,
    "Framework Overhead": 0.54
  },
  "memory_breakdown": [
    {
      "label": "Base Model Weights",
      "value": 79.4,
      "size_gb": 5.43
    },
    {
      "label": "KV Cache",
      "value": 7.6,
      "size_gb": 0.52
    }
  ],
  "runtime_advisories": [
    {
      "code": "PREFILL_STARVATION_RISK",
      "severity": "warning",
      "message": "Full-prompt prefill on long contexts stalls continuous batching token generation, causing high P99 latency jitter."
    }
  ]
};

响应 Body：微调示例

微调输出

{
  "vram_usage": 32.4,
  "vram_percentage": 40.5,
  "actual_vram_percentage": 40.5,
  "memory_status": "okay",
  "static_shared_memory": 24.5,
  "training_tps": 12.0,
  "samples_per_second": 1.5,
  "steps_per_second": 0.18,
  "total_tokens": 10000000.0,
  "total_training_time_hours": 4.5,
  "estimated_system_ram_required": 32.0,
  "offloaded_memory": 0.0,
  "estimated_power_draw": 650,
  "active_optimizations": [
    "gradient_checkpointing",
    "flash_attention"
  ],
  "optimization_preset": "custom",
  "memory_details": {
    "Base Model Weights": 24.5,
    "Optimizer States": 29.4,
    "Gradients": 10.8
  },
  "memory_breakdown": [
    {
      "label": "Base Model Weights",
      "value": 38.2,
      "size_gb": 24.5
    },
    {
      "label": "Optimizer States",
      "value": 45.1,
      "size_gb": 29.4
    },
    {
      "label": "Gradients",
      "value": 16.7,
      "size_gb": 10.8
    }
  ]
}

显存状态枚举选项

memory_status 字段会返回以下小写枚举键之一：

枚举值描述
okay在显存安全范围内，占显存 50% 或更低
moderate处于中度显存占用范围内，占显存 75% 或更低
high占用较高，占显存 90% 或更低
very_high非常接近最大显存容量，超过 90%
insufficient超过可用 GPU 显存容量
errorGPU 配置或规格计算错误

运行时诊断与集群指标

在适用情况下，响应还会包含诊断建议和多节点拓扑指标：

字段类型描述
runtime_advisoriesarray of objects诊断建议对象数组，包含 code、severity 与 message 字段，评估显存碎片流转、KV 交换与硬件瓶颈等情况。
pipeline_asymmetryoptional object流水线并行 pp_degree 大于 1 时的阶段显存不平衡指标，包含 stage_0_vram_gb、final_stage_vram_gb 与 outer_stage_imbalance_ratio。
disaggregated_network_budgetoptional object多节点集群 num_nodes 大于 1 时跨节点 KV 传输的网络带宽与网卡需求，包含 kv_transfer_size_per_request_gb、required_bandwidth_gbs 与 min_nic_line_rate。

运行时建议代码

runtime_advisories 数组返回结构化性能瓶颈与稳定性建议：

建议代码严重级别触发条件与影响

语言模型建议

PCIE_KV_SWAP_HAZARD
warning
通过 PCIe 总线向主机内存交换 KV 缓存，会增加显著的单 token 延迟。
PREFILL_STARVATION_RISK
warning
序列长度达到或超过 4096 时的全量 Prompt Prefill 会阻塞持续批处理 token 生成。
PREFIX_CACHE_ALIGNMENT
advisory
序列长度未对齐运行时 KV 块大小，未对齐的 token 无法共享缓存。
SPECULATIVE_KV_REDUCTION
advisory
投机草稿模型显存占用减少了可用 KV 缓存容量并降低并发上限拐点。

扩散与视频模型建议

VAE_UNTILED_OOM_HAZARD
warning
在未启用 VAE 分块的情况下运行视频生成会导致最终解码步骤显存碎片剧增。启用 VAE 分块可避免显存溢出错误。

分布式与并行架构建议

PIPELINE_STAGE_ASYMMETRY
warning
由于嵌入层和输出投影层，外层阶段需要更多显存，容量规划必须考虑阶段间显存不平衡。
INTER_NODE_TP_BOTTLENECK
warning
张量并行度超过单节点 GPU 数量，跨节点网络集合通信 All-Reduce 会引入严重延迟惩罚。

硬件与模型列表路由

GET
/api/v1/vram-calculation/gpus

获取有效的 gpu_key 参数、硬件模型及显存大小。

curl https://apxml.com/api/v1/vram-calculation/gpus \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"
[
  {
    "key": "rtx_4090",
    "label": "NVIDIA GeForce RTX 4090",
    "memory": 24
  },
  {
    "key": "h100_80",
    "label": "NVIDIA H100 80GB",
    "memory": 80
  }
]
GET
/api/v1/vram-calculation/llms

获取支持的 llm_key 参数以及相对应的模型变体配置。支持查询分页参数如 page 与 limit，例如 ?page=1&limit=100。

curl https://apxml.com/api/v1/vram-calculation/llms \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"
[
  {
    "key": "llama-3-8b-instruct",
    "name": "Llama 3 8B Instruct"
  },
  {
    "key": "llama-3.1-70b-instruct",
    "name": "Llama 3.1 70B Instruct"
  }
]

©2025 趋近智 (ApX Machine Learning)

关于趋近智定价联系我们使用条款隐私政策