开源Forge框架：8B模型Agent准确率飙升至99%

什么是 Forge

自托管 LLM 工具调用的可靠性层。你给 Forge 一组工具，模型可以按任意顺序调用任何工具。工作流结构是可选的——required_steps、prerequisites 和 terminal_tool 让你在需要时对循环施加约束，但 Forge 的护栏（rescue 解析、重试提示、响应验证）即使在没有任何必需步骤时也能工作。

Forge 将一个 8B 本地模型从个位数提升到 Forge 的 26 场景 v0.7.0 评估套件中的 84%——甚至把 Sonnet 4.6 从 85% 提升到同一工作负载上的 98%（Anthropic 的数据在 v0.6.0 中测量；由于成本较高，未在 v0.7.0 中重新运行）。

不是 agent 编排器。Forge 位于单个 agentic 循环内部，使其工具调用可靠。多 agent 图、DAG 规划器和跨 agent 协调超出了范围。

不是编码工具。Forge 是领域无关的。如果你在构建编码 agent（或已在使用 opencode、aider、Cline 等），代理模式使用 Forge 的护栏提升你的现有工具——不需要重写。

三种使用方式

代理服务器——一个插件式代理（python -m forge.proxy）同时支持 OpenAI 聊天补全和 Anthropic Messages（/v1/messages）API，位于任何客户端和本地模型服务器之间。指向与 OpenAI 兼容的工具（opencode、Continue、aider）或 Claude Code，Forge 会透明地应用护栏——客户端认为它在与更聪明的模型对话。最受欢迎的入口点。

WorkflowRunner——定义工具、选择后端、运行结构化的 agent 循环。Forge 管理完整的生命周期：系统提示、工具执行、上下文压缩和护栏。SlotWorker 为共享推理槽增加优先级队列访问和自动抢占——适合多个专家工作流共享 GPU 槽的多 agent 架构。最适合在 Forge 之上直接构建。

护栏中间件——在你自己的编排循环内使用 Forge 的可靠性栈（可组合的中间件）。你控制循环；Forge 验证响应、rescue 格式错误的工具调用，并强制执行必需的步骤。

支持 Ollama、llama-server（llama.cpp）、Llamafile、vLLM 和 Anthropic 作为后端。

快速开始

要求

• 一个运行中的 LLM 后端（见下文）

安装

pip install forge-guardrails                # 仅核心
pip install "forge-guardrails[anthropic]"   # + Anthropic 客户端

或从源代码安装：

git clone https://github.com/antoinezambelli/forge.git
cd forge
pip install -e ".[dev]"

后端设置（选一个）

llama-server（推荐——top 10 的评估配置都在 llama-server 上运行）：

# 从 https://github.com/ggml-org/llama.cpp/releases 安装
llama-server -m path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf --jinja -ngl 999 --port 8080

Ollama（替代方案——设置更简单，在更困难的工作负载上稍弱）：

# 从 https://ollama.com/download 安装
ollama pull ministral-3:8b-instruct-2512-q4_K_M

Anthropic（API，无需本地 GPU）：

pip install -e ".[anthropic]"
export ANTHROPIC_API_KEY=sk-...

更多说明见后端设置；具体使用的模型见模型指南。

你的第一个工作流

按照你通常的方式启动 llama-server（例如在另一个 shell 中）：

llama-server -m path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf --jinja -ngl 999 --port 8080

然后运行你将运行的 Python（例如从另一个 shell）：

import asyncio
from pydantic import BaseModel, Field
from forge import (
    Workflow, ToolDef, ToolSpec,
    WorkflowRunner, LlamafileClient,
    ContextManager, TieredCompact,
)

def get_weather(city: str) -> str:
    return f"72°F and sunny in {city}"

class GetWeatherParams(BaseModel):
    city: str = Field(description="City name")

workflow = Workflow(
    name="weather",
    description="Look up weather for a city.",
    tools={
        "get_weather": ToolDef(
            spec=ToolSpec(
                name="get_weather",
                description="Get current weather",
                parameters=GetWeatherParams,
            ),
            callable=get_weather,
        ),
    },
    required_steps=[],
    terminal_tool="get_weather",
    system_prompt_template="You are a helpful assistant. Use the available tools to answer the user.",
)

async def main():
    client = LlamafileClient(
        gguf_path="path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf",
        mode="native",
        recommended_sampling=True,
    )
    ctx = ContextManager(strategy=TieredCompact(keep_recent=2), budget_tokens=8192)
    runner = WorkflowRunner(client=client, context_manager=ctx)
    await runner.run(workflow, "What's the weather in Paris?")

asyncio.run(main())

关于多步工作流、多轮对话和后端自动管理，见用户指南。如果你在构建长期运行的会话（CLI、聊天服务器、语音助手），见长期运行会话建议，了解对过滤临时消息的重要指导。

代理模式

一个插件式代理，位于任何客户端和本地模型服务器之间，同时支持 OpenAI 聊天补全 API 和 Anthropic Messages API（/v1/messages）。将你的客户端指向代理（例如 http://localhost:8081/v1），Forge 会透明地应用其护栏——客户端认为它在与更聪明的模型对话。

这是使用 Forge 与现有工具（opencode、Continue、aider、Cline，任何支持 OpenAI 聊天补全 schema 的东西——或 Claude Code，支持 Anthropic Messages API）的路径。无需 Python 重写。推理重放默认为无：Forge 仍会捕获推理用于可观测性，但在后续转数时将其保留在面向后端的历史记录之外——最节省 token 的策略，在评估套件上与 replay-all 的统计上无法区分（见推理重放结果）。使用 --reasoning-replay keep-last 仅重放最新的推理块，或使用 --reasoning-replay full 获得历史 replay-all 行为。

启动代理

# 外部模式——你管理后端，Forge 代理它
python -m forge.proxy --backend-url http://localhost:8080 --port 8081

# 托管模式——Forge 同时启动后端和代理
python -m forge.proxy --backend llamaserver --gguf path/to/model.gguf --port 8081

# 托管 vLLM——通过 --model-path 传递模型目录或 HF repo id
python -m forge.proxy --backend vllm --model-path /path/to/awq-dir --port 8081

然后配置你的客户端使用 http://localhost:8081/v1 作为 API base URL。

Claude Code： 代理也在 POST /v1/messages 上提供 Anthropic Messages API，所以你可以将 Claude Code 指向一个 Forge 保护的本地模型——为 claude 进程设置 ANTHROPIC_BASE_URL=http://localhost:8081 和 ANTHROPIC_AUTH_TOKEN=anything。见《使用 Forge 与 Claude Code》了解完整的设置（native vs prompt FC、Anthropic 形状的下游、cache_control）。

后端兼容性

托管模式 为你启动后端。支持的后端：llamaserver、llamafile、ollama、vllm（将 --backend <name> 与基于 GGUF 的后端的 --gguf 一起使用，vllm 使用 --model-path，或 ollama 使用 --model）。

外部模式 是后端无关的——Forge 向你指向的任何东西发送 POST /v1/chat/completions，只要它支持 OpenAI schema。工具调用必须以 OpenAI tool_calls 格式或 Forge 的 rescue 解析格式之一返回（Mistral [TOOL_CALLS]、Qwen <tool_call> XML、fenced JSON）。对于 vLLM 服务器，添加 --backend vllm 以便代理采用 vLLM 的 --served-model-name（不像 llama.cpp，vLLM 在模型字段不匹配时会返回 404）。显式的 --model 会覆盖该发现——对于托管多模型网关（一个列出许多模型的 /v1/models 端点），固定你的模型并跳过发现：--backend vllm --model <name> --budget-tokens <n> --backend-api-key <key>。

代理模式的保护

在每个 POST /v1/chat/completions 上，Forge 应用（按顺序）：

响应验证——模型响应中的每个工具调用都是针对请求中的工具数组进行检查的。对未知工具名称的调用或格式错误的调用在响应返回到你的客户端之前被捕获。

Rescue 解析——当模型以错误的格式发出工具调用时（代码围栏中的 JSON、Mistral 的 [TOOL_CALLS]name{args}、Qwen 的 <tool_call>...</tool_call> XML），Forge 提取结构化调用并以规范的 OpenAI tool_calls schema 重新发出。对 Mistral 系列模型最大的实际提升。

带有错误追踪的重试循环——如果验证失败，Forge 最多重试推理 --max-retries（默认 3）次，在规范通道上使用纠正的 tool-result 消息，而不是返回格式错误的响应。从你的客户端的角度来看，代理看起来像一个只是多花了几毫秒的单个请求。

合成 respond 工具注入——当请求中存在工具时，Forge 注入一个合成 respond 工具，模型调用这个工具而不是生成裸文本。respond 调用从出站响应中被剥离——客户端看到正常的文本响应（finish_reason: "stop"），永远不知道该工具的存在。对于无法被信任正确选择文本和工具调用之间的小型本地模型（~8B）来说是必不可少的。见 ADR-013 了解完整分析。

代理模式不做的事情

代理模式是每个请求的单次调用；某些 Forge 特性需要 OpenAI 聊天补全 schema 不支持的多轮工作流状态：

前置条件强制和步骤排序——这些需要跨轮的工作流定义。在 WorkflowRunner 中可用。

上下文压缩和会话内存——代理模式按原样转发入站消息列表；管理滚动窗口是客户端的工作。

VRAM 感知的预算检测——使用 --budget-mode forge-full 或 --budget-mode forge-fast 选择加入；否则代理使用后端报告的预算。

关于完整的护栏表面，直接使用 WorkflowRunner。代理用"将 Forge 与你的现有设置一起使用，不需要重写"来交换深度。

Docker

你可以将 Forge 代理作为 Docker 容器运行。

docker build -t forge-proxy .

# 连接到外部后端（例如 vLLM 托管在同一台机器上）
docker run -p 8081:8081 forge-proxy --backend-url http://host.docker.internal:8000 --backend vllm --budget-mode manual --budget-tokens 8192

注意：如果你的后端在主机的 localhost 上运行，使用 http://host.docker.internal:PORT（在 macOS/Windows 上）或主机的 IP 地址以允许容器到达它。

见后端设置了解安装和模型指南来选择模型。

测试

python -m pytest tests/ -v --tb=short

覆盖率报告：

python -m pytest tests/ --cov=forge --cov-report=term-missing

评估

26 个场景测量模型 + 后端组合在多步工具调用工作流中导航的可靠程度——分为 OG-18 基准层和 8 场景 advanced_reasoning 层以实现顶级分离。见评估指南了解完整的 CLI 参考。

# llama-server（先在另一个终端启动；见评估指南）
python -m tests.eval.eval_runner --backend llamafile --llamafile-mode prompt --gguf "path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf" --runs 10 --stream --verbose

# 批量评估（JSONL 输出，自动恢复）
python -m tests.eval.batch_eval --config all --runs 50

# 报告——默认为 ASCII 表；--html / --markdown 导出视图
python -m tests.eval.report eval_results.jsonl
python -m tests.eval.report eval_results.jsonl --html docs/results/dashboard.html
python -m tests.eval.report eval_results.jsonl --markdown docs/results/

项目结构

src/forge/
  __init__.py          # 公共 API 导出
  errors.py            # ForgeError 层级
  server.py            # setup_backend()、ServerManager、BudgetMode
  core/
    messages.py        # Message、MessageRole、MessageType、MessageMeta
    workflow.py        # ToolSpec、ToolDef、ToolCall、TextResponse、Workflow
    inference.py       # run_inference() —— 共享前半部分（compact、fold、validate、retry）
    runner.py          # WorkflowRunner —— agentic 循环
    slot_worker.py     # SlotWorker —— 优先级队列槽访问
    steps.py           # StepTracker
  guardrails/
    guardrails.py      # Guardrails 外观 —— 在外部循环中应用完整的栈
    nudge.py           # Nudge 数据类
    response_validator.py  # ResponseValidator、ValidationResult
    step_enforcer.py   # StepEnforcer、StepCheck
    error_tracker.py   # ErrorTracker
  clients/
    base.py            # ChunkType、StreamChunk、LLMClient 协议
    ollama.py          # OllamaClient（原生 FC）
    llamafile.py       # LlamafileClient（原生 FC 或 prompt 注入）
    anthropic.py       # AnthropicClient（前沿基准）
  context/
    manager.py         # ContextManager、CompactEvent
    strategies.py      # CompactStrategy、NoCompact、TieredCompact、SlidingWindowCompact
    hardware.py        # HardwareProfile、detect_hardware()
  prompts/
    templates.py       # 工具提示构建器（prompt 注入路径）
    nudges.py          # 重试和步骤强制 nudge 模板
  tools/
    respond.py         # 合成 respond 工具（respond_tool()、respond_spec()）
  proxy/
    __main__.py        # CLI 入口点：python -m forge.proxy
    proxy.py           # ProxyServer —— 编程启动/停止 API
    server.py          # 原始 asyncio HTTP 服务器、SSE 流
    handler.py         # 请求处理器 —— HTTP 和 run_inference 之间的桥梁
    convert.py         # OpenAI 消息 ↔ Forge Messages 转换
tests/
  unit/                # 865 个确定性测试 —— 不需要 LLM 后端
  eval/                # 评估工具 —— 针对真实后端的模型资格认证

文档

• 用户指南——使用模式、多轮、上下文管理、护栏、slot worker、长期运行会话建议
• 模型指南——适合你的硬件的模型和后端
• 后端设置——后端安装和服务器设置
• 评估指南——评估工具 CLI 参考、批量评估
• 架构——完整的设计文档
• 工作流内部——工作流设计和运行器内部
• 贡献——如何设置、测试以及添加新后端或场景

出版物

Forge 护栏框架和消融研究发表为：

Zambelli, A. Forge: A Reliability Layer for Self-Hosted LLM Tool-Calling. https://doi.org/10.1145/3786335.3813193

也可在 docs/forge_ieee_preprint.pdf 获得发布前预印本——作为历史文物保留。引用上述发表版本；DOI 链接可能不会立即解析，具体取决于出版商的发布时间。

许可证

MIT——版权所有 (c) 2025-2026 Antoine Zambelli