antoinezambelli/forge

来源：https://github.com/antoinezambelli/forge

forge

PyPI (https://pypi.org/project/forge-guardrails/) 测试 (https://github.com/antoinezambelli/forge/actions/workflows/tests.yml) codecov (https://codecov.io/gh/antoinezambelli/forge) Python 3.12+ (https://www.python.org/downloads/) 许可证：MIT

自托管 LLM 工具调用的可靠性层。Forge 通过防护栏（救援解析、重试提示、步骤强制执行）和上下文管理（VRAM 感知预算、分层压缩），将 8B 本地模型提升至多步骤智能体工作流的顶尖水平。当前最佳自托管配置（Ministral-3 8B Instruct Q8 在 llama-server 上）在 forge 的 26 场景评估套件中得分 86.5%，在最高难度级别中得分 76%。

三种使用方式：

• WorkflowRunner — 定义工具、选择后端、运行结构化智能体循环。Forge 管理完整生命周期：系统提示、工具执行、上下文压缩和防护栏。SlotWorker 增加了优先级队列共享推理槽，支持自动抢占——适用于专业工作流共享 GPU 槽的多智能体架构。最适合直接基于 forge 构建时使用。

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

• 代理服务器 — 即开即用的 OpenAI 兼容代理（python -m forge.proxy），位于任何客户端（opencode、Continue、aider 等）与本地模型服务器之间。透明地应用防护栏——客户端会以为它正在与更智能的模型对话。

支持 Ollama、llama-server（llama.cpp）、Llamafile 和 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-...

完整说明请参见后端设置，根据硬件选择模型请参见模型指南。

快速开始

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

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

class GetWeatherParams(BaseModel):
    city: str = Field(description="城市名称")

workflow = Workflow(
    name="weather",
    description="查询某城市的天气。",
    tools={
        "get_weather": ToolDef(
            spec=ToolSpec(
                name="get_weather",
                description="获取当前天气",
                parameters=GetWeatherParams,
            ),
            callable=get_weather,
        ),
    },
    required_steps=[],
    terminal_tool="get_weather",
    system_prompt_template="你是一个乐于助人的助手。使用可用工具回答用户。",
)

async def main():
    client = OllamaClient(model="ministral-3:8b-instruct-2512-q4_K_M", recommended_sampling=True)
    ctx = ContextManager(strategy=TieredCompact(keep_recent=2), budget_tokens=8192)
    runner = WorkflowRunner(client=client, context_manager=ctx)
    await runner.run(workflow, "巴黎的天气怎么样？")

asyncio.run(main())

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

代理服务器

可代替本地模型服务器的即开即用组件。将任何 OpenAI 兼容客户端指向代理，即可免费获得 forge 的防护栏。

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

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

然后将客户端配置为使用 http://localhost:8081/v1 作为 API 基础 URL。

注意： 当请求中包含工具时，代理会自动注入一个合成 respond 工具。模型调用 respond(message="...") 而不是直接输出文本，从而保持在工具调用模式，此时 forge 的完整防护栏堆栈会发挥作用。出站响应中会剥离 respond 调用——客户端会看到一个正常的文本响应（finish_reason: "stop"），完全不知道这个工具的存在。这对于小型本地模型（~8B）至关重要，因为它们无法可靠地在文本和工具调用之间做出选择——引导它们使用工具是必须的。完整分析请参见 ADR-013。

后端

详情请参见后端设置进行安装，或参见模型指南选择模型。

运行测试

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

项目结构

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() — 共享前半部分（压缩、折叠、验证、重试）
    runner.py          # WorkflowRunner — 智能体循环
    slot_worker.py     # SlotWorker — 优先级队列槽访问
    steps.py           # StepTracker
  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 或提示注入）
    anthropic.py       # AnthropicClient（前沿基线）
  context/
    manager.py         # ContextManager、CompactEvent
    strategies.py      # CompactStrategy、NoCompact、TieredCompact、SlidingWindowCompact
    hardware.py        # HardwareProfile、detect_hardware()
  prompts/
    templates.py       # 工具提示构建器（提示注入路径）
    nudges.py          # 重试和步骤强制执行提示模板
  tools/
    respond.py         # 合成 respond 工具（respond_tool()、respond_spec()）
  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/                # 评估工具 — 针对真实后端的模型资格认证

文档

• 用户指南 — 使用模式、多轮对话、上下文管理、防护栏、槽工作者、长期会话建议
• 模型指南 — 根据硬件选择模型和后端
• 后端设置 — 后端安装和服务器设置
• 评估指南 — 评估工具 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