ref(upstream): FULL TREE — Deep-Spark xllm (1470) + ds_vllm csrc/models (703)

Replaces cherry-picked upstream_ref with complete source trees.

xllm/ — Iluvatar official C++ inference engine (15MB, 1470 files)
  Complete: kernels → layers → models → runtime → scheduler → api
  Excluded: .git, binary images, third_party submodule checkouts

ds_vllm/ — Iluvatar official vllm fork (8MB, 703 files)
  Included: csrc/ (ALL CUDA kernels), fused_moe/, qwen3_5 model, _custom_ops
  Excluded: tests, benchmarks, docs, examples (not needed for reference)

Critical call chains now fully traceable:
  MoE: moe_topk_softmax_kernels.cuh → ixformer.h → fused_moe.cpp → layer
  GDN: qwen3_gated_delta_net_base.cpp → qwen3_5_gated_delta_net.cpp
  Attention: ixformer.h → xllm_paged_attention → attention.cpp

upstream_ref/xllm/examples/generate.py

@@ -0,0 +1,34 @@
+# python examples/generate.py --model='/path/models/Qwen2-7B-Instruct' --devices='npu:0'
+# python generate.py --model='/path/models/Qwen2-7B-Instruct' --devices='npu:0,npu:1'
+
+from xllm import ArgumentParser, LLM, SamplingParams
+
+# Create an LLM.
+parser = ArgumentParser()
+llm = LLM(**vars(parser.parse_args()))
+
+# Create sampling params.
+sampling_params = SamplingParams(
+    temperature=0.8,
+    top_p=0.95,
+    max_tokens=10,
+)
+
+# Generate texts from the prompts. The output is a list of RequestOutput
+# objects that contain the prompt, generated text, and other information.
+prompts = [
+    "Hello, my name is",
+    "The president of the United States is",
+    "The capital of France is",
+    "The future of AI is",
+]
+
+outputs = llm.generate(prompts, sampling_params=sampling_params)
+
+# Print the outputs.
+for i, output in enumerate(outputs):
+    prompt = output.prompt
+    generated_text = output.outputs[0].text
+    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")
+
+llm.finish()

upstream_ref/xllm/examples/generate_beam_search.py

@@ -0,0 +1,29 @@
+# python examples/beam_search.py --model='/path/models/Qwen2-7B-Instruct' --devices='npu:0'
+# python beam_search.py --model='/path/models/Qwen2-7B-Instruct' --devices='npu:0,npu:1'
+
+from xllm import ArgumentParser, BeamSearchParams, LLM
+
+# Create an LLM.
+parser = ArgumentParser()
+llm = LLM(**vars(parser.parse_args()))
+
+beam_search_params = BeamSearchParams(
+    beam_width=2,
+    max_tokens=20,
+)
+
+outputs = llm.beam_search(
+    [
+     {"prompt": "Hello, my name is "},
+     {"prompt": "The president of the United States is "},
+     {"prompt": "The capital of France is "},
+     {"prompt": "The future of AI is "}
+    ],
+    params=beam_search_params,
+)
+
+for output in outputs:
+    generated_text = output.sequences[0].text
+    print(f"Generated text: {generated_text!r}")
+
+llm.finish()

upstream_ref/xllm/examples/generate_embedding.py

@@ -0,0 +1,30 @@
+# python examples/generate_embedding.py --model='/path/models/Qwen3-8B' --devices='npu:0' --runner pooling
+# python generate_embedding.py --model='/path/models/Qwen3-8B' --devices='npu:0,npu:1'
+
+from xllm import ArgumentParser, LLM, PoolingParams
+
+# Create an embedding LLM.
+parser = ArgumentParser()
+args = parser.parse_args()
+llm = LLM(**vars(args))
+
+# Create pooling params.
+pooling_params = PoolingParams()
+
+inputs = [
+    "Hello, my name is",
+    "The president of the United States is",
+    "The capital of France is",
+    "The future of AI is",
+]
+
+outputs = llm.embed(inputs, pooling_params=pooling_params)
+
+# Print the outputs.
+for i, output in enumerate(outputs):
+    input_str = output.prompt
+    generated_embedding = output.outputs.embedding
+    print(f"Input: {input_str!r}, Generated embedding: {generated_embedding!r}")
+
+llm.finish()
+

upstream_ref/xllm/examples/generate_vlm.py

@@ -0,0 +1,75 @@
+# python generate_vlm.py --model /path/to/Qwen2.5-VL-7B-Instruct/ --disable_prefix_cache --disable_chunked_prefill --max_seqs_per_batch 4 --devices='npu:0' --enable_shm
+
+from xllm import ArgumentParser, SamplingParams
+from xllm import LLM
+# from xllm import VLM
+import base64
+import os
+
+def encode_image_from_file(file_path: str) -> str:
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"not found image: {file_path}")
+    with open(file_path, "rb") as image_file:
+        result = base64.b64encode(image_file.read()).decode("utf-8")
+    return result
+
+parser = ArgumentParser()
+args = parser.parse_args()
+# vlm = VLM(**vars(args))
+vlm = LLM(**vars(args))
+
+
+image_1 = "./images/3.jpg"
+image_2 = "./images/4.jpg"
+
+# image_base64_1 = encode_image_from_file(image_1)
+# image_base64_2 = encode_image_from_file(image_2)
+
+# image_1 = f"data:image/jpeg;base64,{image_base64_1}"
+# image_2 = f"data:image/jpeg;base64,{image_base64_2}"
+
+requests = [
+    {
+        "prompt": (
+            "<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n"
+            "<|im_start|>user\n"
+            "<|vision_start|><|image_pad|><|vision_end|>"
+            "请描述这张图片。<|im_end|>\n"
+            "<|im_start|>assistant\n"
+        ),
+        "multi_modal_data": {
+            "image": image_1,
+        },
+    },
+    {
+        "prompt": (
+            "<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n"
+            "<|im_start|>user\n"
+            "<|vision_start|><|image_pad|><|vision_end|>"
+            "<|vision_start|><|image_pad|><|vision_end|>"
+            "请对比这两张图片的主要区别。<|im_end|>\n"
+            "<|im_start|>assistant\n"
+        ),
+        "multi_modal_data": {
+            "image": [image_1, image_2],
+        },
+    },
+]
+
+sampling_params = SamplingParams(
+    temperature=0.8,
+    top_p=0.95,
+    max_tokens=50,
+)
+
+outputs = vlm.generate(
+    requests,
+    sampling_params=sampling_params
+)
+
+for output in outputs:
+    prompt = output.prompt
+    generated_text = output.outputs[0].text
+    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")
+
+vlm.finish()

upstream_ref/xllm/examples/sample.py

@@ -0,0 +1,51 @@
+# python examples/sample.py --model='/path/models/Qwen3-8B' --devices='npu:0'
+# python examples/sample.py --model='/path/models/Qwen3-8B' --devices='npu:0,npu:1'
+
+from xllm import ArgumentParser, LLM, RequestParams
+
+# Create an LLM.
+parser = ArgumentParser()
+llm = LLM(**vars(parser.parse_args()))
+
+# selector must be a stable single special token in the target tokenizer.
+selector = "masked"
+
+prompts = [
+    f"candidate_a={selector}, candidate_b={selector}",
+    f"user_feature={selector}",
+]
+
+# RequestParams can still carry generic sampling knobs.
+# sample() will enforce:
+# - max_tokens=1
+# - n=1
+# - best_of=1
+# - logprobs=True
+request_params_list = []
+for _ in prompts:
+    request_params = RequestParams()
+    request_params.temperature = 0.0
+    request_params.top_p = 1.0
+    request_params_list.append(request_params)
+
+outputs = llm.sample(
+    prompts,
+    selector=selector,
+    request_params=request_params_list,
+    logprobs=5,
+    wait_schedule_done=True,
+)
+
+# One RequestOutput per input prompt.
+# output.outputs is expanded by selector hits in that prompt.
+for i, output in enumerate(outputs):
+    print(f"[prompt-{i}] {output.prompt!r}")
+    for sample_output in output.outputs:
+        print(
+            f"  sample_id={sample_output.index}, "
+            f"token={sample_output.text!r}, "
+            f"token_ids={sample_output.token_ids}, "
+            f"finish_reason={sample_output.finish_reason}"
+        )
+
+llm.finish()