forge

环境要求

• Python 3.12 或更高版本
• 一个正在运行的 LLM 后端（llama-server / Ollama / Anthropic API 三选一）
• 本地运行 llama-server 或 Ollama 需要可用的硬件（无本地 GPU 时可改用 Anthropic API）
• 如需使用 Docker 代理，本机需安装 Docker

安装与启动步骤

1. 1确认 Python 版本

   forge 的 Python 包要求 Python 3.12+，版本不符需先升级 Python 再继续安装。

   python --version

   复制

2. 2安装 forge 核心包

   安装核心库，用于 WorkflowRunner、guardrails 中间件、开发或 Python 托管的 Proxy。

   pip install forge-guardrails

   复制

3. 3开发模式安装

   需要改源码或跑测试时用开发模式安装，会一并装上开发依赖。

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

   复制

4. 4启动 llama-server

   推荐的本地后端，官方评测前十配置均基于 llama-server；需先从 llama.cpp 发布页安装。

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

   复制

5. 5安装 Anthropic 后端

   没有本地 GPU 时可用 Anthropic API 替代本地后端，先装额外依赖再导出密钥。

   pip install "forge-guardrails[anthropic]"
   export ANTHROPIC_API_KEY=sk-xxxxxxxx

   复制

6. 6运行 Quick Start 示例

   把 README 的示例代码保存为 .py 文件，先在另一个终端启动 llama-server，再运行该脚本。

7. 7构建代理 Docker 镜像

   在仓库根目录执行，把 forge 代理打包成名为 forge-proxy 的镜像。

   docker build -t forge-proxy .

   复制

关键配置

如何确认成功

运行 python -m pytest tests/ -v --tb=short 全部通过，或 Quick Start 脚本成功返回工具调用结果。

常见问题

注意事项

• 必须先有一个运行中的 LLM 后端，forge 本身不包含模型。
• Python 包不提供全局 forge-proxy 命令，代理统一用 python -m forge.proxy 运行。
• llama-server 命令中的 -ngl 999 与 --port 8080 来自 README 示例，可按实际硬件调整。
• 修改代理相关代码后，建议按 CONTRIBUTING.md 运行确定性代理冒烟测试与真实后端检查。