Kimi-K2.5

graph LR
    A --3--> B
    A --5--> C
    B --7--> D
    C --1--> D
    D --2--> E

def tpool_patch_merger(
        x: torch.Tensor,
        grid_thws: torch.Tensor,
        merge_kernel_size: tuple[int, int] = (2, 2),
) -> list[torch.Tensor]:
    d_model = x.size(-1)

    outputs = []
    pre_sum = 0
    for t, h, w in grid_thws.tolist():
        # Get the current sequence
        seq = x[pre_sum:pre_sum + t * h * w]
        # Reshape along self.merge_kernel_size and concat to the last dimension
        kernel_height, kernel_width = merge_kernel_size
        new_height, new_width = h // kernel_height, w // kernel_width
        reshaped_seq = seq.view(t, new_height, kernel_height, new_width,
                                kernel_width, d_model)
        reshaped_seq = reshaped_seq.permute(0, 1,
                                            3, 2, 4, 5).contiguous().mean(
                                                dim=0)  # temporal pooling
        padded_seq = reshaped_seq.view(new_height * new_width,
                                       kernel_height * kernel_width, -1)
        outputs.append(padded_seq)
        pre_sum += t * h * w

    return outputs

----------------
ubuntu 22.04
python 3.12
cuda 12.8
pytorch 2.8.0
----------------

python -m pip install --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

pip install modelscope
pip install vllm

from modelscope import snapshot_download

model_dir = snapshot_download('moonshotai/Kimi-K2.5', cache_dir='/root/autodl-tmp', revision='master')

from vllm import LLM, SamplingParams
from transformers import AutoTokenizer
import os
import json

# 自动下载模型时，指定使用modelscope; 否则，会从HuggingFace下载
os.environ['VLLM_USE_MODELSCOPE']='True'

def get_completion(prompts, model, tokenizer=None, temperature=0.6, top_p=0.95, top_k=20, min_p=0, max_tokens=4096, max_model_len=8192):
    stop_token_ids = [151645, 151643]
    # 创建采样参数。temperature 控制生成文本的多样性，top_p 控制核心采样的概率，top_k 通过限制候选词的数量来控制生成文本的质量和多样性, min_p 通过设置概率阈值来筛选候选词，从而在保证文本质量的同时增加多样性
    sampling_params = SamplingParams(temperature=temperature, top_p=top_p, top_k=top_k, min_p=min_p, max_tokens=max_tokens, stop_token_ids=stop_token_ids)  # max_tokens 用于限制模型在推理过程中生成的最大输出长度
    # 初始化 vLLM 推理引擎
    llm = LLM(model=model, tokenizer=tokenizer, max_model_len=max_model_len,trust_remote_code=True, tensor_parallel_size=8)  # max_model_len 用于限制模型在推理过程中可以处理的最大输入和输出长度之和。
    outputs = llm.generate(prompts, sampling_params)
    return outputs


if __name__ == "__main__":
    # 初始化 vLLM 推理引擎
    model='/root/autodl-fs/moonshotai/Kimi-K2.5' # 指定模型路径
    tokenizer = AutoTokenizer.from_pretrained(model) # 加载分词器

    prompt = "给我一个关于大模型的简短介绍。"
    messages = [
        {"role": "user", "content": prompt}
    ]
    text = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True,
        enable_thinking=True  # 是否开启思考模式，默认为 True
    )

    outputs = get_completion(text, model, tokenizer=None, temperature=0.6, top_p = 0.95, top_k=20, min_p=0)  # 对于思考模式，官方建议使用以下参数：temperature = 0.6，TopP = 0.95，TopK = 20，MinP = 0。

    # 输出是一个包含 prompt、生成文本和其他信息的 RequestOutput 对象列表。
    # 打印输出。
    for output in outputs:
        prompt = output.prompt
        generated_text = output.outputs[0].text
        print(f"Prompt: {prompt!r}, \nResponse: {generated_text!r}")

python vllm_model.py

Prompt: '<|im_user|>user<|im_middle|>给我一个关于大模型的简短介绍。<|im_end|><|im_assistant|>assistant<|im_middle|><think>', 
Response: ' 用户要求一个关于大模型的简短介绍。我需要提供一个简洁、准确且全面的概述，涵盖大模型的基本概念、特点和应用。\n\n关键点应该包括：\n1. 什么是大模型（Large Language Models/LLMs或Foundation Models）\n2. 核心特点（参数规模大、训练数据多、涌现能力等）\n3. 主要应用领域\n4. 简要的技术背景（Transformer架构、预训练+微调范式）\n5. 当前主流代表（GPT、Claude、文心一言等）\n\n需要保持简短，控制在200-300字左右，语言通俗易懂但专业准确。\n\n结构建议：\n- 定义（1-2句）\n- 技术特点（1-2句）\n- 能力表现（1-2句）\n- 应用场景（1句）\n- 局限性提示（可选，简要）\n\n让我组织一下内容：\n\n大模型（Large Language Models，LLM）是基于深度学习技术的人工智能系统，通常包含数十亿至数千亿参数，通过海量文本数据训练而成。它们以Transformer架构为基础，采用"预训练+微调"的技术路线，具备强大的语言理解、生成和推理能力。\n\n这类模型的核心特征包括规模效应（参数越多能力越强）、上下文学习（In-context Learning）和涌现能力（Emergent Abilities）。典型代表如GPT-4、Claude、文心一言等，已广泛应用于智能客服、内容创作、代码生成、知识问答等领域。\n\n尽管大模型展现出接近人类的语言交互能力，但仍存在幻觉（生成虚假信息）、知识时效性等局限，通常需要结合检索增强（RAG）等技术来提升可靠性。\n\n字数检查：约200字，符合"简短介绍"的要求。内容涵盖了定义、技术、应用和局限，比较全面。 </think> 大模型（Large Language Models，LLM）是基于深度学习的人工智能系统，通常包含数十亿至数千亿参数，通过海量文本数据训练而成。它们以Transformer架构为基础，采用"预训练+微调"的技术路线，具备强大的语言理解、生成和推理能力。\n\n这类模型的核心特征包括**规模效应**（参数越多能力越强）、**上下文学习**（无需微调即可适应新任务）和**涌现能力**（复杂能力的突然出现）。典型代表如GPT-4、Claude、文心一言等，已广泛应用于智能客服、内容创作、代码生成、知识问答等领域。\n\n尽管大模型展现出接近人类的语言交互能力，但仍存在**幻觉**（生成虚假信息）、知识时效性等局限，实际应用中常需结合检索增强（RAG）等技术提升可靠性。'

VLLM_USE_MODELSCOPE=true vllm serve /root/autodl-fs/moonshotai/Kimi-K2.5 -tp 8 --max_model_len 8192 --trust-remote-code --tool-call-parser kimi_k2 --reasoning-parser kimi_k2

curl http://localhost:8000/v1/models

{
    "object": "list",
    "data": [
        {
            "id": "/root/autodl-fs/moonshotai/Kimi-K2.5",
            "object": "model",
            "created": 1770228068,
            "owned_by": "vllm",
            "root": "/root/autodl-fs/moonshotai/Kimi-K2.5",
            "parent": null,
            "max_model_len": 8192,
            "permission": [
                {
                    "id": "modelperm-91d23e09c5068ccb",
                    "object": "model_permission",
                    "created": 1770228068,
                    "allow_create_engine": false,
                    "allow_sampling": true,
                    "allow_logprobs": true,
                    "allow_search_indices": false,
                    "allow_view": true,
                    "allow_fine_tuning": false,
                    "organization": "*",
                    "group": null,
                    "is_blocking": false
                }
            ]
        }
    ]
}

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "/root/autodl-fs/moonshotai/Kimi-K2.5",
        "prompt": "我想问你，什么是深度学习算法？<think>\n",
        "max_tokens": 1024,
        "temperature": 0
    }'

{
    "id": "cmpl-899843517a844968",
    "object": "text_completion",
    "created": 1770228473,
    "model": "/root/autodl-fs/moonshotai/Kimi-K2.5",
    "choices": [
        {
            "index": 0,
            "text": "深度学习算法是机器学习的一个子集，它基于人工神经网络，特别是具有多个隐藏层的神经网络（因此称为“深度”）。这些算法通过模拟人脑处理信息的方式来学习数据的复杂模式和表示。\n\n## 核心特点\n\n| 特点 | 说明 |\n|------|------|\n| **多层结构** | 包含输入层、多个隐藏层和输出层 |\n| **自动特征提取** | 无需人工设计特征，自动从原始数据中学习 |\n| **端到端学习** | 直接从输入映射到输出 |\n| **大数据需求** | 通常需要大量训练数据 |\n| **计算密集** | 依赖GPU等硬件加速 |\n\n## 主要架构类型\n\n1. **卷积神经网络 (CNN)** — 图像处理、计算机视觉\n2. **循环神经网络 (RNN/LSTM)** — 序列数据、自然语言处理\n3. **Transformer** — 现代NLP主流（如GPT、BERT）\n4. **生成对抗网络 (GAN)** — 生成新数据\n5. **自编码器 (Autoencoder)** — 降维、特征学习\n\n## 简单比喻\n\n> 想象教小孩认猫：传统机器学习需要你先告诉它\"猫有尖耳朵、胡须、毛茸茸\"；而深度学习只需给它看成千上万张猫的照片，它自己就能总结出\"猫\"的概念。\n\n## 典型应用\n\n- 语音识别（Siri、Alexa）\n- 图像识别（人脸识别、医学影像）\n- 自然语言处理（机器翻译、ChatGPT）\n- 自动驾驶\n- 推荐系统\n\n你想深入了解哪个具体方面？比如训练过程、某种网络结构，或者实际应用？",
            "logprobs": null,
            "finish_reason": "stop",
            "stop_reason": 163586,
            "token_ids": null,
            "prompt_logprobs": null,
            "prompt_token_ids": null
        }
    ],
    "service_tier": null,
    "system_fingerprint": null,
    "usage": {
        "prompt_tokens": 9,
        "total_tokens": 352,
        "completion_tokens": 343,
        "prompt_tokens_details": null
    },
    "kv_transfer_params": null
}

from openai import OpenAI
openai_api_key = "sk-xxx" # 随便填写，只是为了通过接口参数校验
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

chat_outputs = client.chat.completions.create(
    model="/root/autodl-fs/moonshotai/Kimi-K2.5",
    messages=[
        {"role": "user", "content": "什么是大模型？"},
    ]
)
print(chat_outputs)

python vllm_openai_chat_completions.py

ChatCompletion(id='chatcmpl-af0cb04e8460c288', choices=[Choice(finish_reason='stop', index=0, logprobs=None, message=ChatCompletionMessage(content=' **大模型**（Large Models，通常指大语言模型LLM）是指参数量巨大（通常数十亿到数千亿级别）、训练数据海量、计算资源需求极高的机器学习模型，尤其是基于深度学习的模型。\n\n以下是核心要点解析：\n\n## 1. 本质特征：「大」在哪里？\n- **参数规模大**：从数十亿（如GPT-3有1750亿参数）到万亿级别（如GPT-4据传超过1万亿），这些参数是模型学习到的"知识"的数学表示\n- **训练数据大**：需要TB甚至PB级别的文本、图像、代码等数据（相当于阅读了人类大部分公开知识）\n- **计算资源大**：训练一次需要数千张高端GPU/TPU运行数周至数月，成本可达数百万美元\n\n## 2. 技术基础\n主要基于**Transformer架构**（2017年Google提出），通过"注意力机制"（Attention）理解文本中词语之间的长距离关联，突破传统RNN的顺序处理限制。\n\n## 3. 核心能力（涌现现象）\n当模型达到特定规模后，会突然表现出小模型不具备的能力：\n- **上下文理解**：理解复杂指令和长篇对话\n- **推理能力**：数学计算、逻辑推演、代码生成\n- **知识整合**：跨领域知识迁移和综合\n- **少样本学习**（Few-shot）：仅需几个示例就能掌握新任务\n\n## 4. 典型代表\n- **国外**：GPT-4/4o（OpenAI）、Claude（Anthropic）、Gemini（Google）、Llama（Meta）\n- **国内**：文心一言（百度）、通义千问（阿里）、讯飞星火、智谱ChatGLM、DeepSeek等\n\n## 5. 与中小模型的区别\n| 维度 | 大模型 | 传统小模型 |\n|------|--------|------------|\n| 参数 | 十亿级以上 | 百万-千万级 |\n| 训练方式 | 预训练+微调 | 针对特定任务训练 |\n| 泛化能力 | 通用性强，跨领域 | 专用性强，领域狭窄 |\n| 使用方式 | 提示词（Prompt）驱动 | 需要特征工程 |\n\n## 6. 局限性\n- **幻觉**（Hallucination）：可能生成看似合理但错误的信息\n- **计算成本高**：推理需要大量算力\n- **数据偏见**：可能继承训练数据中的偏见\n- **可解释性差**：内部决策机制如同"黑箱"\n\n**简单比喻**：如果把AI比作大脑，传统模型是专精某科的"专科生"（如只会识别猫狗的视觉模型），大模型则是博览群书的"通才博士"，能通过语言理解并处理各种复杂任务，但偶尔也会"一本正经地胡说八道"。', refusal=None, role='assistant', annotations=None, audio=None, function_call=None, tool_calls=[], reasoning=' 用户问的是"什么是大模型？"这是一个关于人工智能领域的基础概念问题。我需要用中文清晰、准确地解释这个概念。\n\n 大模型（Large Language Models 或 Large Models）的关键点包括：\n 1. 定义：参数量巨大的机器学习模型，通常是深度学习模型\n 2. 规模：数十亿到数千亿甚至万亿级别的参数\n 3. 技术基础：基于Transformer架构的神经网络\n 4. 训练数据：海量的文本、图像等多模态数据\n 5. 能力：涌现能力（Emergent abilities），如推理、生成、理解上下文等\n 6. 代表：GPT系列、BERT、文心一言、通义千问等\n 7. 应用：聊天机器人、代码生成、内容创作等\n\n 我应该从基础到深入，用通俗易懂的方式解释，同时保持技术准确性。\n\n 结构建议：\n 1. 简单定义（是什么）\n 2. 核心特征（为什么"大"）\n 3. 工作原理（简要技术解释）\n 4. 主要能力（能做什么）\n 5. 典型代表（举例）\n 6. 局限性（平衡视角）\n\n 避免过于技术化的术语，但关键概念如"参数"、"Transformer"、"预训练"等需要提及并简要解释。 ', reasoning_content=' 用户问的是"什么是大模型？"这是一个关于人工智能领域的基础概念问题。我需要用中文清晰、准确地解释这个概念。\n\n 大模型（Large Language Models 或 Large Models）的关键点包括：\n 1. 定义：参数量巨大的机器学习模型，通常是深度学习模型\n 2. 规模：数十亿到数千亿甚至万亿级别的参数\n 3. 技术基础：基于Transformer架构的神经网络\n 4. 训练数据：海量的文本、图像等多模态数据\n 5. 能力：涌现能力（Emergent abilities），如推理、生成、理解上下文等\n 6. 代表：GPT系列、BERT、文心一言、通义千问等\n 7. 应用：聊天机器人、代码生成、内容创作等\n\n 我应该从基础到深入，用通俗易懂的方式解释，同时保持技术准确性。\n\n 结构建议：\n 1. 简单定义（是什么）\n 2. 核心特征（为什么"大"）\n 3. 工作原理（简要技术解释）\n 4. 主要能力（能做什么）\n 5. 典型代表（举例）\n 6. 局限性（平衡视角）\n\n 避免过于技术化的术语，但关键概念如"参数"、"Transformer"、"预训练"等需要提及并简要解释。 '), stop_reason=163586, token_ids=None)], created=1770228828, model='/root/autodl-fs/moonshotai/Kimi-K2.5', object='chat.completion', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=847, prompt_tokens=12, total_tokens=859, completion_tokens_details=None, prompt_tokens_details=None), prompt_logprobs=None, prompt_token_ids=None, kv_transfer_params=None)

from openai import OpenAI

client = OpenAI(
    api_key="a", # 随便填
    base_url="http://localhost:8000/v1"
)

def add(a: float, b: float):
    return a + b

def mul(a: float, b: float):
    return a * b

def compare(a: float, b: float):
    if a > b:
        return f'{a} is greater than {b}'
    elif a < b:
        return f'{b} is greater than {a}'
    else:
        return f'{a} is equal to {b}'

def count_letter_in_string(a: str, b: str):
    string = a.lower()
    letter = b.lower()
  
    count = string.count(letter)
    return(f"The letter '{letter}' appears {count} times in the string.")


tools = [
{
    'type': 'function',
    'function': {
        'name': 'add',
        'description': 'Compute the sum of two numbers',
        'parameters': {
            'type': 'object',
            'properties': {
                'a': {
                    'type': 'int',
                    'description': 'A number',
                },
                'b': {
                    'type': 'int',
                    'description': 'A number',
                },
            },
            'required': ['a', 'b'],
        },
    }
}, 
{
    'type': 'function',
    'function': {
        'name': 'mul',
        'description': 'Calculate the product of two numbers',
        'parameters': {
            'type': 'object',
            'properties': {
                'a': {
                    'type': 'int',
                    'description': 'A number',
                },
                'b': {
                    'type': 'int',
                    'description': 'A number',
                },
            },
            'required': ['a', 'b'],
        },
    }
},
{
    'type': 'function',
    'function': {
        'name': 'count_letter_in_string',
        'description': 'Count letter number in a string',
        'parameters': {
            'type': 'object',
            'properties': {
                'a': {
                    'type': 'str',
                    'description': 'source string',
                },
                'b': {
                    'type': 'str',
                    'description': 'letter',
                },
            },
            'required': ['a', 'b'],
        },
    }
},
{
    'type': 'function',
    'function': {
        'name': 'compare',
        'description': 'Compare two number, which one is bigger',
        'parameters': {
            'type': 'object',
            'properties': {
                'a': {
                    'type': 'float',
                    'description': 'A number',
                },
                'b': {
                    'type': 'float',
                    'description': 'A number',
                },
            },
            'required': ['a', 'b'],
        },
    }
}
]

def function_call_playground(prompt):
    messages = [{'role': 'user', 'content': prompt}]
    response = client.chat.completions.create(
        model="/root/autodl-fs/moonshotai/Kimi-K2.5",
        messages = messages,
        temperature=0.01,
        top_p=0.95,
        stream=False,
        tools=tools)

    # print(response)
    func1_name = response.choices[0].message.tool_calls[0].function.name
    func1_args = response.choices[0].message.tool_calls[0].function.arguments
    func1_out = eval(f'{func1_name}(**{func1_args})')
    # print(func1_out)

    messages.append(response.choices[0].message)
    messages.append({
        'role': 'tool',
        'content': f'{func1_out}',
        'tool_call_id': response.choices[0].message.tool_calls[0].id
    })
    # print(messages)
    response = client.chat.completions.create(
        model="/root/autodl-fs/moonshotai/Kimi-K2.5",
        messages=messages,
        temperature=0.01,
        top_p=0.95,
        stream=False,
        tools=tools)
    return response.choices[0].message.content
  
prompts = [
    "用中文回答：strawberry中有多少个r?", 
    "用中文回答：9.11和9.9，哪个小?"
]

for prompt in prompts:
    print(function_call_playground(prompt))

python vllm_openai_chat_completions.py

在字符串"strawberry"中，字母'r'出现了3次。
9.11比9.9小。

根据比较结果，9.9比9.11大，所以9.11更小。

from modelscope import snapshot_download

# 下载 Kimi-K2.5 模型
model_dir = snapshot_download(
    'moonshotai/Kimi-K2.5', 
    cache_dir='./kimi_models', 
    revision='master'
)

print(f"模型下载完成，存储路径为: {model_dir}")

# 创建并激活环境，明确 python 版本和安装 pip， -y则跳过各种确认
conda create -n sglang python=3.12 pip -y
conda activate sglang

# 更新 pip 版本
python -m pip install --upgrade pip

# 源码安装 SGLang
pip install "sglang @ git+https://github.com/sgl-project/sglang.git#subdirectory=python"

# 安装特定的 cudnn 版本以优化性能
pip install nvidia-cudnn-cu12==9.16.0.29

# 请将 $MODEL_PATH 替换为您实际的文件夹路径
sglang serve --model-path /your/path/to/Kimi-K2.5 --tp 8 --trust-remote-code --tool-call-parser kimi_k2 --reasoning-parser kimi_k2

import openai

client = openai.Client(
    base_url="http://127.0.0.1:30000/v1", 
    api_key="empty"
)

response = client.chat.completions.create(
    model="default",
    messages=[
        {"role": "user", "content": "你好 Kimi，请介绍一下你自己，并确认一下你现在的版本。"}
    ],
    temperature=0.7
)

print(f"Kimi 的回答：\n{response.choices[0].message.content}")

Kimi 的回答：
你好！我是 **Kimi**，由 **月之暗面科技有限公司**（Moonshot AI）开发的人工智能助手。

关于我目前的版本：**我现在运行的是 Kimi K2.5**（知识截止于 2025 年 1 月）。

作为一名 AI 助手，我能够：

- **多语言交流**：流利使用中文、英文等多种语言进行对话
- **长文本处理**：支持超长上下文窗口（最高可达 200 万字级别），能够阅读和分析长篇文档、论文、书籍等
- **文件理解**：可以解析 PDF、Word、图片等多种格式的文件内容
- **联网搜索**：获取最新信息（取决于当前功能配置）
- **代码与技术**：协助编程、调试、解释技术概念
- **创意与写作**：帮助撰写文章、润色文本、头脑风暴等

如果你有任何问题、需要分析文档、写代码，或者只是想聊聊天，随时告诉我！今天有什么我可以帮你的吗？

import sys
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:30000/v1", 
    api_key="empty"
)

def chat_stream(prompt):
    print(f"User: {prompt}")
    print("Kimi: ", end="", flush=True)

    try:
        response = client.chat.completions.create(
            model="default",
            messages=[
                {"role": "system", "content": "你是由月之暗面开发的Kimi2.5，现在运行在高性能的SGLang后端。"},
                {"role": "user", "content": prompt}
            ],
            temperature=0.7,
            stream=True  # 核心参数：开启流式传输
        )

        for chunk in response:
            content = chunk.choices[0].delta.content
            if content is not None:
                print(content, end="", flush=True)

        print("\n" + "-"*30)
    except Exception as e:
        print(f"\n[错误]: {e}")

if __name__ == "__main__":
    chat_stream("请详细介绍一下 SGLang 的 RadixAttention 技术及其优势。")

User: 请详细介绍一下 SGLang 的 RadixAttention 缓存技术，并分点说明它的优势。
Kimi: 
 SGLang 的 **RadixAttention** 是一种基于**基数树（Radix Tree）**的 KV 缓存（Key-Value Cache）管理技术，专为高效处理大型语言模型（LLM）推理中的**前缀复用**而设计。它是 SGLang  runtime 的核心优化之一，能够自动识别和共享不同请求间相同的 token 序列前缀，从而避免重复计算。

以下是详细的技术解析及其优势：

---

### 一、核心技术原理

#### 1. **基数树（Radix Tree）索引结构**
RadixAttention 将 KV 缓存组织成一棵基数树（压缩前缀树）：
- **节点（Node）**：代表一个 token 序列段（通常对应一个固定大小的缓存块，如 16/32/64 个 token）。
- **边（Edge）**：标记为具体的 token ID 序列。
- **叶节点到根节点的路径**：构成完整的 token 序列及其对应的 KV 缓存块。

#### 2. **块级（Block-level）缓存管理**
- 将连续的 KV 缓存划分为固定大小的**物理块**（Physical Blocks）。
- 每个块通过其包含的 token 内容的哈希值在基数树中索引。
- 支持**细粒度共享**：不同请求可以共享树中的部分路径（前缀），而独占后续分支。

#### 3. **自动前缀匹配（Automatic Prefix Matching）**
当新请求到达时：
- 系统遍历基数树，寻找与输入序列**最长的公共前缀**。
- **完全匹配**的节点对应的 KV 缓存块被直接复用（"命中"）。
- **未匹配部分**触发新的计算，并动态插入树中作为新分支。

#### 4. **动态内存管理**
- **引用计数（Reference Counting）**：跟踪每个缓存块被多少个活跃请求或历史会话引用。
- **LRU 驱逐策略**：当 GPU 内存不足时，自动驱逐最近最少使用的叶节点块，释放内存。

---

### 二、主要优势（分点说明）

#### 1. **显著减少重复计算，提升吞吐量**
- **场景**：多轮对话（历史上下文作为前缀）、批量推理（共享 System Prompt）、Agent 工作流（重复的工具调用模板）。
- **效果**：公共前缀只需计算一次 KV 缓存，后续请求直接复用。实测可将多轮对话的**首 token 延迟（TTFT）降低 5-10 倍**，整体吞吐量提升 2-5 倍。

#### 2. **透明化的自动缓存复用**
- **零配置**：开发者无需手动管理缓存键（cache key）或显式指定哪些部分需要缓存。
- **智能匹配**：自动处理部分匹配、重叠序列，甚至支持非连续前缀的复用（通过树的结构特性）。

#### 3. **高效的内存共享与隔离**
- **写时复制（Copy-on-Write）**：当某个请求需要修改共享前缀后的内容时，系统仅复制必要的块，保持前缀部分的共享状态，避免内存浪费。
- **细粒度隔离**：不同会话的后缀部分独立存储，互不干扰，确保逻辑正确性。

#### 4. **优化长上下文（Long Context）性能**
- 对于超长文档问答或代码仓库级推理，RadixAttention 能缓存文档本身的 KV 表示。
- 当用户针对同一文档提出不同问题时，只需计算问题部分的 KV，文档部分的缓存即时可用，极大缓解长上下文带来的计算压力。

#### 5. **降低 GPU 内存碎片**
- 基于块的分配策略（类似操作系统的分页）减少了动态内存分配产生的碎片。
- 基数树的压缩特性（合并单 child 节点）减少了索引本身的内存开销。

#### 6. **与解码优化协同工作**
- 与 **Continous Batching** 结合：在等待新请求时，已缓存的前缀可立即用于构造新 batch，减少 GPU 空闲时间。
- 与 **Speculative Decoding** 结合：草稿模型和主模型可共享前缀缓存，进一步加速。

---

### 三、典型应用场景

| 场景 | 优化效果 |
|------|---------|
| **多轮对话系统** | 第 N 轮对话直接复用前 N-1 轮的 KV 缓存，仅计算最新一轮的增量。 |
| **批量 API 调用** | 一批请求共享相同的 System Prompt 和工具描述，只需计算一次前缀。 |
| **Agent 工作流** | 重复的 ReAct 模式（Thought -> Action -> Observation）中，固定模板部分被自动缓存。 |
| **代码补全/生成** | 同一文件内的多次补全请求共享文件前缀的 KV 缓存。 |

---

### 四、与类似技术的区别

- **vs. vLLM PagedAttention**：PagedAttention 主要解决**显存碎片化和动态 batching** 问题（通过块表映射虚拟/物理块）；而 **RadixAttention 专注于前缀复用和共享**（通过基数树索引）。两者正交，SGLang 实际上也借鉴了分页思想来实现 RadixAttention 的底层存储。
- **vs. 手动 Prompt Cache**：RadixAttention 是自动的、细粒度的（块级），而传统手动缓存通常是整个 prompt 级别的，灵活性低。

总结来说，RadixAttention 通过基数树实现了 KV 缓存的**结构化复用**，在保持完全自动化的同时，显著提升了 LLM 服务在处理交互式、长上下文和批量任务时的效率和响应速度。

import openai
import json
import requests 

# --- !!! 请在这里替换你的真实 API KEY !!! ---
OPENWEATHERMAP_API_KEY = ""

## 调用API 获取实时天气信息的函数
def get_weather_realtime(location: str, unit: str) -> str:
    units_map = {"celsius": "metric", "fahrenheit": "imperial"}
    url = "http://api.openweathermap.org/data/2.5/weather"
    params = {
        "q": location,
        "appid": OPENWEATHERMAP_API_KEY,
        "units": units_map.get(unit, "metric") # 默认使用摄氏度
    }

    try:
        # 发起请求
        response = requests.get(url, params=params, timeout=5)
        response.raise_for_status() 
        data = response.json()

        # 提取关键信息 (API 返回格式)
        if data.get("cod") == 200:
            temp = data["main"]["temp"]
            description = data["weather"][0]["description"]
            city_name = data["name"]
            
            result = {
                "location": city_name,
                "temperature": f"{temp}",
                "unit": unit,
                "condition": description,
                "source": "OpenWeatherMap"
            }
            # 返回 JSON 字符串给 LLM
            return json.dumps(result, ensure_ascii=False)
        else:
            return json.dumps({"error": f"城市 '{location}' 未找到", "code": data.get("cod")})

    except requests.exceptions.HTTPError as e:
        return json.dumps({"error": f"HTTP错误: {e.response.status_code}. 城市名称可能不正确。", "location": location})
    except requests.exceptions.RequestException as e:
        return json.dumps({"error": "网络连接或超时失败。", "details": str(e), "location": location})
    except Exception as e:
        return json.dumps({"error": "数据解析失败。", "details": str(e), "location": location})


## 初始化 OpenAI 客户端和工具

client = openai.Client(
    base_url="http://127.0.0.1:30000/v1", 
    api_key="empty"
)
tool_functions = {"get_weather": get_weather_realtime}

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取一个给定地点的当前实时天气情况，如查询不到则返回错误信息。",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "城市名，例如：北京, Tokyo, London"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location", "unit"]
        }
    }
}]

## 第一次 API 调用：Kimi 规划——获得天气信息，但是并非自然语言查询，而是结构化的工具调用
user_query = "What's the weather like in Baoji? use celsius."
response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": user_query}],
    tools=tools,
    tool_choice="auto"
)

response_message = response.choices[0].message

tool_call = response_message.tool_calls[0].function
function_name = tool_call.name
arguments_str = tool_call.arguments
print(f"Kimi 规划: 函数 {function_name}, 参数 {arguments_str}")

args_dict = json.loads(arguments_str)
real_result_str = tool_functions[function_name](**args_dict)
print(f"API 真实返回结果: {real_result_str}")

## 第二次 API 调用：Kimi 总结——将 API 的结果进行总结，给出最终的自然语言的回答
messages = [
    {"role": "user", "content": user_query},
    response_message,
    {
        "tool_call_id": response_message.tool_calls[0].id,
        "role": "tool",
        "name": function_name,
        "content": real_result_str,
    }
]

final_response = client.chat.completions.create(
    model="default",
    messages=messages
)

final_answer = final_response.choices[0].message.content
print("\n✅ Kimi 的最终回答:\n", final_answer)

Kimi 规划: 函数 get_weather, 参数 {"location": "Baoji", "unit": "celsius"}
API 真实返回结果: {"location": "Baoji", "temperature": "-0.67", "unit": "celsius", "condition": "overcast clouds", "source": "OpenWeatherMap"}

✅ Kimi 的最终回答:
 In Baoji (宝鸡), it's currently **-0.7°C** with **overcast clouds**.

That's right around freezing, so it's quite chilly! Make sure to bundle up if you're heading out.