forge

Forge 是一个用于自托管 LLM 工具调用（tool-calling）的可靠性层。你可以为 forge 提供一组工具，模型将以任意顺序调用所需的工具。工作流结构是可选的 —— 你可以在需要时使用 required_steps、prerequisites 和 terminal_tool 来约束循环，但即便不配置任何步骤，forge 的护栏功能（修复解析、重试引导、响应验证）也能生效。

在 forge 的 26 个场景 v0.7.0 评测套件中，它能将 8B 参数的本地模型从极低的成功率提升至 84%；在相同的负载下，它甚至能将 Sonnet 4.6 的表现从 85% 提升至 98%（Anthropic 的数据是在 v0.6.0 中测得；鉴于成本较高，v0.7.0 未重新测试）。

Forge 不是什么：

• 不是代理编排器（Agent Orchestrator）。 Forge 位于单个 Agent 循环内部，负责确保其工具调用的可靠性。多 Agent 图、DAG 规划器和跨 Agent 协调均不在其范围内。
• 不是编码框架（Coding Harness）。 Forge 是领域无关的。如果你正在构建编码 Agent（或者已经在使用 opencode、aider、Cline 等工具），代理模式（Proxy mode） 可以通过 forge 的护栏功能增强你现有的工具链，无需重写任何代码。

三种使用方式：

• 代理服务器 (Proxy server) — 即插即用的代理（python -m forge.proxy），支持 OpenAI chat-completions 和 Anthropic Messages (/v1/messages) API，位于任何客户端和本地模型服务器之间。将 OpenAI 兼容的工具（opencode、Continue、aider）或 Claude Code 指向它，forge 即可透明地应用护栏功能——客户端会认为它正在与一个更智能的模型对话。这是最受欢迎的入口点。

• WorkflowRunner — 定义工具、选择后端、运行结构化的 Agent 循环。Forge 管理完整的生命周期：系统提示词、工具执行、上下文压缩和护栏。SlotWorker 增加了对共享推理槽的优先级排队访问及自动抢占功能——适用于多个专业化工作流共享 GPU 资源的场景。当你直接基于 forge 进行构建时，这是最佳选择。

• 护栏中间件 (Guardrails middleware) — 在你自己的编排循环中使用 forge 的可靠性堆栈（可组合中间件）。你控制循环逻辑；forge 负责验证响应、修复格式错误的工具调用并强制执行必需步骤。

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

环境要求

• Python 3.12+
• 运行中的 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（推荐 — 排名前 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-...

请参阅 后端设置 (Backend Setup) 获取完整说明，并查看 模型指南 (Model Guide) 以了解哪种模型适合你的硬件。

快速入门

按照通常方式启动 llama-server（例如在单独的终端中）：

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

然后在 Python 中运行（例如在另一个终端中）：

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 ans