ScaleDown 中间件集成

使用 LangChain Python 集成 ScaleDown 中间件。

ScaleDown 限制解码模型的中件层集成。ScaleDown 限制解码模型每个都针对狭窄任务进行训练，因此它们在智能体周围的高量级步骤（如压缩历史记录或读取长工具结果）的处理速度更快、成本更低，比对通用模型的第二次调用更高效。智能体保留自己的模型用于规划和生成。了解更多关于 中件层。]

所有ScaleDown中间件均遵循开放失败策略。如果ScaleDown不可用、信用不足或拒绝请求，智能体会像没有该中间件一样运行，并会记录警告信息。

Middleware	Description
Summarization	Replace older messages with a summary once the context fills up
Context compression	Compress a large system prompt relative to the user’s question
Tool result compression	Let the model request only the relevant part of a tool’s output
Extraction	Pull structured fields out of the user’s messages into agent state

设置

要使用 ScaleDown 中间件，请创建 ScaleDown 账号，从 ScaleDown dashboard 获取 API key 并安装 langchain-scaledown 包。新账号包含 50 亿免费 Token。

凭证

Set API key

import getpass
import os

if "SCALEDOWN_API_KEY" not in os.environ:
    os.environ["SCALEDOWN_API_KEY"] = getpass.getpass("Enter your ScaleDown API key: ")

每个中间件都会读取 SCALEDOWN_API_KEY。若需指向不同的 API 主机，请设置 SCALEDOWN_BASE_URL。若需在中间件之间共享一个连接，请创建 ScaledownClient 并将其作为 client=传递给每个中间件。

它也有助于（但不是必需的）设置 LangSmith 用于可观察性和跟踪。要启用自动跟踪，请设置您的 LangSmith API 密钥：

Enable tracing

os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"

安装

ScaleDown 中间件位于 langchain-scaledown 包中：

pip

pip install -U langchain-scaledown

摘要

长时间运行的智能体会耗尽上下文。每次历史记录填满时，通过调用通用模型来总结旧历史记录会增加成本和延迟。ScaledownSummarizer 使用 ScaleDown 来写入摘要，并通过其 summarizer 参数接入内置的 SummarizationMiddleware。内置的中间件仍然决定何时总结以及保留哪些最近消息。

默认摘要与LangChain的提示词模板包含相同的部分：会话意图、摘要、附件和后续步骤。

ScaleDown 总结输出限制在 200 个 Token，因此 max_tokens 超过该值的输出会被 API 限制。

Summarizer with SummarizationMiddleware

from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware
from langchain_scaledown import ScaledownSummarizer

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[read_file, write_file, run_tests],
    middleware=[
        SummarizationMiddleware(
            model="claude-sonnet-4-6",  # Used for its context window and token counting
            trigger=("fraction", 0.8),
            keep=("fraction", 0.1),
            trim_tokens_to_summarize=None,  # Send all older history to ScaleDown
            summarizer=ScaledownSummarizer(),  
        ),
    ],
)

ScaledownSummarizationMiddleware 是相同设置的快捷方式，只有一个区别：如果 ScaleDown 调用失败，它会保留历史记录不变，并正常调用模型。

ScaledownSummarizationMiddleware

from langchain.agents import create_agent
from langchain_scaledown import ScaledownSummarizationMiddleware

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[read_file, write_file, run_tests],
    middleware=[
        ScaledownSummarizationMiddleware(  
            "claude-sonnet-4-6",
            trigger=("fraction", 0.8),
            keep=("fraction", 0.1),
        ),
    ],
)

深度智能体摘要中间件接受相同的 summarizer 参数。它还将被驱逐的历史记录保存到一个智能体可以读取的文件中。

Configuration options

instructions · string | None

规则附加到 ScaleDown 的基本摘要指令上。默认为会话意图、摘要、工件和下一步骤部分。传递 None 以仅使用 ScaleDown 的默认行为。

max_tokens · number · default: "2048"

生成摘要的最大长度。API 会将其限制在其输出限制范围内。

client · ScaledownClient

预配置客户端。如果省略，则从 api_key、base_url 或环境变量创建一个。

上下文压缩

ScaledownCompressionMiddleware 在每次模型调用前，会压缩相对于用户最新问题的较大系统提示词。系统消息是会被压缩的上下文，而最后一个用户消息则是决定要保留内容的查询。用户消息和对话历史会保持不变。

用于“大海捞针”类工作负载，例如检索增强生成（RAG），其中一大块检索到的文档包含少量相关事实。不要用于短提示词或创意生成，因为压缩可能会丢失模型所需的指令、语气或细节。在使用 Deep Agents 时，系统消息也包含 harness 自身的指令，压缩也会将这些内容压缩。

Context compression

from langchain.agents import create_agent
from langchain_scaledown import ScaledownCompressionMiddleware

agent = create_agent(
    model="claude-sonnet-4-6",
    system_prompt=f"Answer using these documents:\n\n{retrieved_docs}",
    middleware=[ScaledownCompressionMiddleware(min_context_chars=2000)],  
)

当系统消息短于 min_context_chars、没有用户消息或 ScaleDown 调用失败时，请求将保持不变。

Configuration options

min_context_chars · number · default: "2000"

仅压缩超过此长度的上下文。

rate · string | number · default: "auto"

传递给 ScaleDown 的压缩率。

context_extractor · Callable

接收模型请求并返回 (context, prompt) 元组的函数，或返回 None 以跳过压缩。压缩后的上下文始终替换系统消息。默认情况下，系统消息作为上下文，最后一个用户消息作为提示词。

工具结果压缩

向支持智能体咨询欧盟订单的退款政策，它可以将商店的整个政策页面引入上下文。后续的每一步都会再次为这些 Token 支付费用。ScaledownToolCompressionMiddleware为您的工具添加了一个可选的compression_query参数。当模型只需要部分结果时，它会填写compression_query，例如"refund policy for EU orders"。中间件在工具运行前移除该参数，然后在模型看到之前将输出压缩为相关部分。

Tool result compression

from langchain.agents import create_agent
from langchain_scaledown import ScaledownToolCompressionMiddleware

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[search_docs, fetch_url],
    middleware=[ScaledownToolCompressionMiddleware(tools=["fetch_url"])],  
)

您的工具不会改变，因此这适用于任何工具，包括 MCP 工具。压缩结果以注释开头，以便模型在需要完整输出时无需 compression_query 就能再次调用工具：

Compression note

[Compressed by ScaleDown for "refund policy for EU orders": 18,402 -> 3,110 chars. Call this tool again without `compression_query` for the full output.]

当模型省略compression_query、输出短于min_result_chars、结果为错误或包含非文本内容，或ScaleDown调用失败时，结果保持不变。

Configuration options

tools · list

要添加参数的工具，或工具名称。默认为智能体拥有的所有工具。

param_name · string · default: "compression_query"

添加的参数的名称。如果目标工具已经有一个具有此名称的参数，则引发 ValueError。

param_description · string

对添加的参数的描述，展示给模型。

min_result_chars · number · default: "4000"

仅压缩长度超过此值的工具输出。

rate · string | number · default: "auto"

ScaleDown 传递的压缩率。

提取

智能体通常需要从用户处获取少量事实信息才能执行操作，例如订单号、遇到的错误或邮箱地址。ScaledownExtractionMiddleware通过ScaleDown替代在每轮对话中向代理模型询问，而是在每次运行前（首次模型调用前）将用户消息和你的架构发送给ScaleDown，并将结果存储在代理状态下的scaledown_extraction中。工具可以在运行期间读取这些信息，最终输出包含在agent.invoke()中。

仅使用用户消息，永不使用代理自身的回复，因此每个提取值都是用户所述内容。请用平白语言描述每个字段：

Extraction

from langchain.agents import create_agent
from langchain.tools import ToolRuntime, tool
from langchain_scaledown import ScaledownExtractionMiddleware

ticket = ScaledownExtractionMiddleware(
    entities={
        "order_id": "Order number the customer mentions",
        "error_message": "Exact error message or code the customer saw",
        "steps_tried": "What the customer says they already tried",
        "customer_email": "Customer's email address",
    },
    context_chars=0,  # Skip evidence snippets to keep state small
)


@tool
def file_ticket(runtime: ToolRuntime) -> str:
    """File a support ticket with the details gathered so far."""
    fields = runtime.state.get("scaledown_extraction", {}).get("fields", {})
    return crm.create_ticket(**fields)  # Your ticketing system


agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[file_ticket],
    middleware=[ticket],  
)

记录按字段逐条记录。未找到的字段显示为None：

Extraction result

result["scaledown_extraction"]["fields"]
# {
#   "order_id": "A-1042",
#   "error_message": "ERR_PAYMENT_DECLINED",
#   "steps_tried": "tried a different card",
#   "customer_email": None,
# }

配合检查点器时，提取会在每轮对话重新运行完整对话，用户补充细节时记录逐步完善。提取值为用户文本。若设置inject_into_prompt=True使模型可见字段，该文本会被添加到系统提示中，需确保仅对可接受字段启用此功能。

Configuration options

entities · dict · required

要提取的字段架构。每个键映射为描述字符串、包含description、threshold、top_n的对象，或嵌套架构。

instruction · string

作用于所有字段的通用指令。

threshold · number

全局置信阈值。默认为API默认值。

top_n · number

每字段最大结果数。默认返回所有匹配。

context_chars · number

每匹配返回的上下文字符数。设为0可缩小代理状态体积。

text_builder · Callable

根据对话消息构建提取文本的函数。默认仅使用用户消息文本。

inject_into_prompt · boolean · default: "False"

每模型调用后追加提取字段至系统消息。

API参考

获取所有ScaleDown类源码和完整参数文档，请参考langchain-scaledown仓库。

---

官方原文：src/oss/python/integrations/middleware/scaledown.mdx · 非官方翻译，译文由 AI 生成，以英文原文为准。