سناریوی رخداد

چهار راه‌اندازی ناموفق بعد از pip install

Four failed starts after a pip install

  • سطح ۲: میانی
  • سناریوی رخداد
  • ۲۰ دقیقه

وضعیت

تیم پلتفرم یک نود جدید با دو کارت L4 تحویل می‌گیرد. روی میزبان، اوبونتو 24.04 همراه با درایور نصب است و هیچ جزء دیگری از CUDA وجود ندارد. آن‌ها SGLang را با pip نصب می‌کنند و فرایند نصب بدون هیچ خطایی به پایان می‌رسد. اولین اجرای sglang serve با پیام کامپایلر C مبنی بر نبود یک هدر (header) متوقف می‌شود. مشکل را برطرف می‌کنند و دوباره استارت می‌زنند. یک خطای تازه ظاهر می‌شود. آن را هم رفع می‌کنند. بعد از یک بعدازظهر تلاش، چهار راه‌اندازی ناموفق و چهار خطای کاملاً متفاوت دارند که هرکدام از یک مؤلفه‌ی جداگانه می‌آید.

تیم دیگر روی همان نود، vLLM را با ابزار uv نصب می‌کند. سرور آن‌ها بلافاصله بعد از ساخت کرنل (kernel) با خطای Engine core initialization failed از کار می‌افتد. حالا هر دو تیم فکر می‌کنند درایور نود خراب است و تیکتی برای نصب مجدد سیستم‌عامل (reimage) ثبت می‌کنند. از شما خواسته شده پیش از خاموش شدن نود، لاگ‌ها را بررسی کنید.

نسخه
SGLang 0.5.22 from pip, and vLLM 0.31.0 from a uv install
مدل
Qwen/Qwen3-8B
سخت‌افزار
a node with two L4 GPUs, an NVIDIA driver and no CUDA toolkit

شواهد

attempt-3-header-mismatch.txt
title: the third start: the compiler and the headers do not match
source: manuals/sglang-101/capture/gpu/incidents/l4-toolchain-failures.txt
lines: 9-13
lang: text
note: The Ninja build of the FlashInfer kernels stops on one preprocessor check in a bundled header.
---
=== attempt: out-l4-jitmismatch/server-default.log
[2026-10-16 14:23:40] RuntimeError: Ninja build failed. Ninja output:
<site-packages>/flashinfer/data/cccl/libcudacxx/include/cuda/std/__cccl/cuda_toolkit.h:41:8: error: #error "CUDA compiler and CUDA toolkit headers are incompatible, please check your include paths"
   41 | #      error "CUDA compiler and CUDA toolkit headers are incompatible, please check your include paths"
<site-packages>/flashinfer/data/cccl/libcudacxx/include/cuda/std/__cccl/cuda_toolkit.h:41:8: error: #error "CUDA compiler and CUDA toolkit headers are incompatible, please check your include paths"
attempt-4-no-libcudart.txt
title: the fourth start: the linker cannot find the CUDA runtime library
source: manuals/sglang-101/capture/gpu/incidents/l4-toolchain-failures.txt
lines: 14-18
lang: text
note: The JIT module of SGLang links against -lcudart and the linker finds no such file.
---
=== attempt: out-l4-nolibcudart/server-default.log
/usr/bin/ld: cannot find -lcudart: No such file or directory
collect2: error: ld returned 1 exit status
[2026-10-16 14:26:33] RuntimeError: Failed to build JIT module sgl_kernel_jit_fused_rope_true_128_false_bf16_t_bf16_t in /root/.cache/sglang/jit/sm89/sgl_kernel_jit_fused_rope_true_128_false_bf16_t_bf16_t/build-d129ad15216edb50/.staging-45436f7697ff4fd58892a3e6760bd970
/usr/bin/ld: cannot find -lcudart: No such file or directory
attempts-1-and-2.txt
title: the first two starts: a missing Python header, then no CUDA compiler
source: manuals/sglang-101/capture/gpu/incidents/l4-toolchain-failures.txt
lines: 1-8
lang: text
note: Read the first error line under each attempt header. The progress bar line repeats the first error.
---
=== attempt: out-l4-nopyheaders/server-default.log
<site-packages>/triton/backends/nvidia/driver.c:9:10: fatal error: Python.h: No such file or directory
<site-packages>/triton/backends/nvidia/driver.c:9:10: fatal error: Python.h: No such file or directory

  0%|          | 0/50 [00:00<?, ?it/s]
Capturing prefill shape (num_tokens=4096 avail_mem=2.28 GB):   0%|          | 0/50 [00:00<?, ?it/s]<site-packages>/triton/backends/nvidia/driver.c:9:10: fatal error: Python.h: No such file or directory
=== attempt: out-l4-nonvcc/server-default.log
[2026-10-16 14:21:19] RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist
    raise RuntimeError(
RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist
other-engine-core-failed.txt
title: the other engine: the engine core fails, and the three packages behind it
source: manuals/vllm-101/capture/gpu/incidents/l4-vllm-flashinfer-jit.txt
lines: 5-8
lang: text
note: Read the versions of the kernel library, the headers and the compiler, which come from three different packages.
---
RuntimeError: Engine core initialization failed. See root cause above. Failed core proc(s): {}
flashinfer_python-0.7.0.post1.dist-info
nvidia_cuda_cccl-13.3.4.3.1.dist-info
nvidia_cuda_nvcc-13.4.92.dist-info
other-engine-jit-build.txt
title: the other engine on the same host: the sampler choice and the JIT build
source: manuals/vllm-101/capture/gpu/incidents/l4-vllm-flashinfer-jit.txt
lines: 1-3
lang: text
note: The second line names the component that the third line starts to build.
---
INFO 10-17 16:22:09 [api_utils.py:286] non-default args: {'model_tag': 'Qwen/Qwen3-8B', 'host': '127.0.0.1', 'port': 30000, 'model': 'Qwen/Qwen3-8B', 'max_model_len': 8192, 'gpu_memory_utilization': 0.9, 'num_gpu_blocks_override': 1506}
INFO 10-17 16:22:26 [topk_topp_sampler.py:124] Using FlashInfer for top-p & top-k sampling.
2026-10-17 16:22:39,316 - INFO - core.py:564 - flashinfer.jit: Building JIT module sampling; this can take several minutes on first use.
the-four-repairs.txt
title: the one fact behind the four failures, and the repair for each
source: manuals/sglang-101/sections/7-1-operating-sglang.md
lines: 50-57
lang: text
note: One numbered item per failed start, in the order the starts failed.
---
All four failures come from one fact. SGLang, Triton, and FlashInfer compile kernels on the target machine at startup, and a compiler needs a complete toolchain.

1. Triton compiles a small C helper against the Python headers. The system Python of Ubuntu has no `Python.h`. We changed to a Python build that includes its headers, from `uv`.
2. SGLang looks for `nvcc` under `/usr/local/cuda`. The pip wheels include `nvcc` 13.4 under `nvidia/cu13` in site-packages, but nothing points to it. We set `CUDA_HOME` to that directory.
3. FlashInfer then compiled its attention kernels with that `nvcc` against its own bundled headers, and the versions did not match. We installed `flashinfer-jit-cache`, which holds kernels compiled in advance for SM 8.9.
4. The JIT kernels of SGLang link with `-lcudart` from `$CUDA_HOME/lib64`. The wheel has only `lib/libcudart.so.13`. We made a `CUDA_HOME` with a `lib64` directory that holds `libcudart.so`.

The fifth start served requests. Our GB10 never had this problem, because its DGX operating system has a full toolkit in `/usr/local/cuda`.
the-sampler-entry.txt
title: the troubleshooting entry for the sampler build on the other engine
source: manuals/vllm-101/sections/7-1-troubleshoot-by-symptom.md
lines: 61-65
lang: text
note: The fix line gives the environment variable that skips the sampler build.
---
### The sampler fails to compile after you set CUDA_HOME

- **Cause:** the toolkit on the host does not match the CUDA build of PyTorch, so the FlashInfer sampler cannot compile. With a host toolkit at nvcc 13.4, we saw this on our L4 node.
- **Check:** the error says `CUDA compiler and CUDA toolkit headers are incompatible`.
- **Fix:** install the toolkit version that matches your PyTorch build. Or start with `VLLM_USE_FLASHINFER_SAMPLER=0`, as [the FP8 KV cache page](#s-fit-more-users-with-an-fp8-kv-cache) does.

سؤال‌ها

  1. چهار خطا از چهار مؤلفه‌ی مختلف نام می‌برند. واقعیت مشترک پشت همه‌ی آن‌ها چیست؟
  2. چرا یک موتور سرویس‌دهی اصلاً به هدرهای پایتون نیاز دارد و کدام بخش از پشته‌ی نرم‌افزاری آن‌ها را خواسته است؟
  3. سومین شکست درست بعد از رفع خطای دوم ظاهر شد. راه‌حل دوم چه پیامدی داشت؟
  4. موتور دوم روی همان میزبان با همان بررسی پیش‌پردازنده با شکست مواجه شد. آیا علت یکسان است؟ راه‌حل تک‌متغیری برای یک بنچمارک با روش حریصانه (greedy benchmark) چیست؟
  5. درباره‌ی تیکت بازنصب سیستم‌عامل چه پاسخی به تیم می‌دهید و راه‌حل محیط عملیاتی چیست؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. اولین خطای هر راه‌اندازی را بخوانید، نه ردگیری محاسبات (traceback) را. تلاش اول در فایل triton/backends/nvidia/driver.c روی خطای Python.h: No such file or directory متوقف می‌شود. Triton هنگام شروع به کار سرور، یک فایل کمکی کوچک به زبان C را در برابر هدرهای پایتون کامپایل می‌کند؛ درحالی‌که پایتون پیش‌فرض سیستم فاقد این هدرهاست. مستندات، سوئیچ به بیلد پایتونی را پیشنهاد داد که هدرهایش را همراه دارد (از طریق uv). تلاش دوم با این خطا متوقف می‌شود: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist. ویل‌های (wheel) نصب‌شده با pip، یک نسخه‌ی 13.4 از nvcc را در مسیر nvidia/cu13 داخل site-packages به همراه دارند، اما هیچ متغیری به آن اشاره نمی‌کرد؛ بنابراین مستندات، متغیر CUDA_HOME را روی همان دایرکتوری تنظیم کرد.
  2. ببینید چطور رفع یک خطا، شکست بعدی را آشکار کرد. با در دسترس قرار گرفتن کامپایلر، FlashInfer کرنل‌های اتنشن (attention) خود را با همان nvcc در برابر هدرهای داخلی همراه خود ساخت و نسخه‌ها با هم نخواندند. فرایند ساخت با Ninja روی یک سطر پیش‌پردازنده متوقف می‌شود: CUDA compiler and CUDA toolkit headers are incompatible. مستندات اقدام به نصب flashinfer-jit-cache کرد؛ بسته‌ای که کرنل‌های از‌پیش‌کامپایل‌شده را برای معماری SM 8.9 نگه می‌دارد تا نیازی به کامپایل مجدد روی میزبان نباشد.
  3. خطای چهارم را به عنوان یک مشکل لینکر (linker) بخوانید. کرنل‌های JIT در SGLang با پرچم -lcudart از مسیر $CUDA_HOME/lib64 لینک می‌شوند. ویل فقط شامل lib/libcudart.so.13 بود و به همین خاطر ld نمی‌توانست فایل libcudart.so را پیدا کند. مستندات یک CUDA_HOME با دایرکتوری lib64 ساخت که این کتابخانه را در خود نگه می‌دارد. در راه‌اندازی پنجم، سرور بالا آمد و به درخواست‌ها پاسخ داد.
  4. موتور دوم را با شکست سوم مقایسه کنید. موتور vLLM کتابخانه‌ی FlashInfer را برای نمونه‌برداری Top-k و top-p انتخاب کرد و ساخت ماژول JIT بخش sampling را آغاز نمود. فرایند ساخت روی همان بررسی هدر متوقف شد و هسته‌ی موتور هرگز بالا نیامد. فهرست بسته‌ها زیر پیام خطا، علت را در سه خط نشان می‌دهد: کتابخانه‌ی کرنل flashinfer_python-0.7.0.post1، هدرهای nvidia_cuda_cccl-13.3.4.3.1 و کامپایلر nvidia_cuda_nvcc-13.4.92 از سه بسته‌ی مجزا با سه نسخه‌ی متفاوت می‌آیند. راهنمای vLLM دو راه‌حل ارائه می‌دهد: استفاده از تول‌کیت سازگار با بیلد PyTorch، یا تنظیم VLLM_USE_FLASHINFER_SAMPLER=0 که ساخت نمونه‌گیر (sampler) را نادیده می‌گیرد و برای یک بنچمارک حریصانه کفایت می‌کند.
  5. واقعیت مشترک را نام ببرید. ابزارهای SGLang، Triton و FlashInfer همگی هنگام راه‌اندازی سرور، کرنل‌ها را روی ماشین مقصد کامپایل می‌کنند و یک کامپایلر به زنجیره‌ابزار (toolchain) کاملی نیاز دارد. درایور اصلاً نقشی در هیچ‌یک از این خطاها نداشت. سرور GB10 در مستندات هیچ‌وقت به این مشکل نخورد، چون سیستم‌عامل DGX آن یک تول‌کیت کامل در مسیر /usr/local/cuda دارد.
نتیجه

بازنصب سیستم‌عامل را لغو کنید. هیچ‌کجای لاگ‌ها اسمی از درایور نیامده است. همه‌ی خطاها به کامپایلر، مجموعه‌ای از هدرها یا لینکر اشاره دارند؛ مواردی که همگی به فرایند ساخت کرنل در زمان اولین راه‌اندازی وابسته‌اند.

برای محیط عملیاتی، SGLang را از طریق ایمیج پین‌شده (pinned image) اجرا کنید، یا آن را روی میزبانی بالا بیاورید که جعبه‌ابزار کامل CUDA روی آن نصب است. روش نصب با pip روی میزبانی که فقط درایور دارد، پس از اعمال چهار مرحله‌ی اصلاحی بالا جواب می‌دهد؛ اما مستندات هشدار می‌دهد که با هر ارتقای SGLang ممکن است دوباره به این اصلاحات نیاز پیدا کنید. برای vLLM، از ایمیج یا تول‌کیتی هماهنگ با بیلد PyTorch استفاده کنید؛ متغیر VLLM_USE_FLASHINFER_SAMPLER=0 را فقط زمانی به کار ببرید که روی یک میزبانِ فاقد آن، قصد اجرای سریع یک بنچمارک حریصانه را دارید. اثبات این راه‌حل، استارت پنجم سرور بود که به درخواست‌ها پاسخ داد، و همچنین موضع صریح مستندات که در پی آن مطرح شد: خارج از ایمیج، سیستم را فقط روی میزبانی با تول‌کیت کامل اجرا کنید.

مسیرهای اشتباه رایج
  • «درایور خراب است، نود را ری‌ایمیج کنید.» هیچ خطایی نامی از درایور نمی‌برد. این چهار پیام به‌ترتیب از سمت کامپایلر C، جستجوی کامپایلر CUDA، بررسی هدرها و لینکر صادر شده‌اند.
  • «دستور pip install بدون خطا تمام شد، پس فرایند نصب کامل است.» این دستور کرنل‌ها را کامپایل نمی‌کند. کامپایل هنگام اولین راه‌اندازی رخ می‌دهد و در همان نقطه سلامت زنجیره‌ابزار سنجیده می‌شود.
  • «تول‌کیت CUDA را از مخازن توزیع لینوکس نصب کنید و ویل‌ها را نگه دارید.» تول‌کیت باید با نسخه‌ی CUDA در بیلد PyTorch دقیقاً مطابقت داشته باشد. روی این نود، تول‌کیت میزبان با nvcc 13.4 باعث خطای عدم تطابق هدرها شد.
  • «یک خطا را برطرف کنید و کار نود را تمام‌شده بدانید.» هر راه‌حل، نقص بعدی را آشکار کرد. پیش از بستن تیکت، حتماً یک راه‌اندازی کامل انجام دهید و دست‌کم یک درخواست به سرور بفرستید.
درس کلی

موتوری که کرنل‌ها را هنگام راه‌اندازی کامپایل می‌کند، یک گام نصب دوم هم دارد؛ گامی که در اولین استارت و دقیقاً روی همان ماشینی که از آن سرویس می‌دهید اجرا می‌شود. هر زمان این مرحله شکست خورد، اولین سطر خطا را بخوانید و ببینید کدام ابزار با مشکل روبرو شده است: کامپایلر، هدرهایی که می‌خواند یا لینکر. زنجیره‌ابزار را اصلاح کنید یا سراغ ایمیجی بروید که همه‌ی این‌ها را به شکل آماده دارد. باگ درایور کارت گرافیک همیشه با پیام‌های اختصاصی خود درایور اعلام می‌شود، نه در لاگ کامپایل پروژه‌ها.

کجای دوره آموزش داده می‌شود

مستندات SGLang این چهار راه‌اندازی و مراحل رفع آن‌ها را در بخش pip install در صفحه‌ی عملیاتی ثبت کرده است. مستندات vLLM نیز بخش‌های متناظری برای نبود کامپایلر و ساخت نمونه‌گیر دارد.