DemensDeum

Notes

Language

通过 FreeLLMAPI 的 OpenCode 免费模型

Written by

demensdeum

in

OpenCode 是一个在终端中工作的开放编程代理：读取项目文件、编辑代码、运行命令和测试、搜索存储库并使用 git。它不依赖于一个模型提供商，因此几乎任何 OpenAI 兼容服务都可以连接到它。

FreeLLMAPI 是一款开放式自托管路由器，可在一个兼容 OpenAI 的 /v1 地址下收集来自数十家 AI 提供商的免费计划。您拥有一个本地网关和一个统一密钥，而不是三十个密钥、三十个限制和三十个可能导致请求失败的位置。路由器本身会选择一个可用的型号，当出现429或5xx错误时切换到下一个型号，并确保请求不超过免关税配额。

在这篇文章中，我将描述安装 FreeLLMAPI、添加提供程序以及将网关连接到 OpenCode。

你需要什么

要工作，你需要四样东西：

  • 已安装 OpenCode。如果尚未安装代理，我会在有关 OpenCode 和 DeepSeek 的单独说明中讨论安装过程。
  • FreeLLMAPI 正在运行。最简单的方法是安装桌面应用程序或 Docker 容器。
  • Node.js 20.18 或更高版本。配置 OpenCode 的 CLI 生成器需要此版本。 OpenCode 本身可以在没有 Node 的情况下安装。
  • 至少一个提供商的密钥。Google AI Studio、Groq、Cerebras、Mistral、OpenRouter、NVIDIA、HuggingFace 以及目录中的其他服务的免费计划均适用。

安装 FreeLLMAPI

该项目有多个安装路径。选择对您的系统更方便的一种。

桌面应用程序

对于 Windows 和 macOS，最简单的选项是发布页面中的现成安装程序。在 Windows 上它是 .exe，在 macOS 上它是 Apple Silicon 或 Intel 的 .dmg。该应用程序位于托盘中，并在本地升起路由器和控制面板。

桌面版本不需要密码：面板通过隐藏的本地帐户自行登录。您需要的唯一凭据是托盘弹出窗口或密钥页面标题中的统一密钥。

应用程序数据位于一个目录中：

  • Windows — %APPDATA%\FreeLLMAPI\
  • macOS — ~/Library/Application Support/FreeLLMAPI/
  • Linux — ~/.config/FreeLLMAPI/

Docker

如果已经安装了 Docker，则可以通过一条命令启动服务器。该脚本创建 ~/freellmapi 目录，生成加密密钥，下载映像并启动容器：

curl -fsSL https://freellmapi.co/install.sh | bash

再次运行脚本是安全的：保存 .env 文件和加密密钥，并将容器更新到最新版本。在 Windows 上，此方法适用于 WSL 或任何 bash 环境。

启动后，面板打开于：

http://localhost:3001

对于服务器安装，您需要使用电子邮件和密码创建一个帐户。如果忘记密码，重置代码会打印在容器日志中：

docker compose logs -f freellmapi

Docker Compose

如果您想将配置保留在 git 中并手动管理启动，则常规 Compose 即可。在 macOS 和 Linux 上：

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
docker compose up -d

在 Windows PowerShell 中：

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
$Bytes = New-Object Byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($Bytes)
$ENCRYPTION_KEY = -join ($Bytes | ForEach-Object { "{0:x2}" -f $_ })
"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env
docker compose up -d

ENCRYPTION_KEY 密钥是必需的：它用于加密 SQLite 数据库中的提供程序密钥。您无法即时更改它 – 旧的秘密将不再被解密。对于轮换，该项目有一个单独的命令“rotate-encryption-key”。

从源代码运行

对于开发或调试，您可以通过 Node.js 运行项目：

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install
ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
npm run dev

该模式下API和面板在3001端口发起，Vite接口在5173端口发起。

首次启动和提供商密钥

打开面板，进入Keys页面，添加我们使用的服务的密钥。对于每个提供商，界面都有一个注册链接和一个获取密钥的提示。从一两个开始就足够了：例如，Google AI Studio 和 Groq。

添加后，密钥将接受健康检查。如果提供商响应错误，密钥将保留在列表中，但将被标记为不健康 – 可以再次检查或删除它。

接下来，您应该转到型号页面并查看可用的型号。您还可以在其中配置路由策略和回退链的顺序 – 发生错误和限制时路由器所沿的链。 auto模型意味着由路由器本身做出选择。除此之外，还可以使用 auto:fast、auto:smart 和针对特定任务的命名配置文件等选项。

还值得检查链中是否有支持工具的模型。 OpenCode 积极使用工具调用，没有此功能的模型将无法正常读取文件或运行命令。

统一密钥在密钥页面上或桌面应用程序的托盘中获取。它看起来像一个带有前缀的字符串：

freellmapi-...

OpenCode 中指示的正是此密钥，而不是各个提供商的密钥。

连接到 OpenCode

FreeLLMAPI 有一个配置生成器，它本身从正在运行的网关读取模型目录，制作现有配置的备份副本，并小心地将提供程序添加到其中。

首先，我们将统一密钥设置为环境变量。生成器读取它而不是单独的标志，因此秘密不会最终出现在命令历史记录中。

在 macOS 和 Linux 上：

export FREELLMAPI_API_KEY=freellmapi-YOUR_KEY

在 Windows PowerShell 中：

$env:FREELLMAPI_API_KEY="freellmapi-YOUR_KEY"

现在让我们看看具体会记录什么：

npx freellmapi setup-opencode --url http://localhost:3001 --dry-run

如果 diff 令人满意，则重复不带标志的命令：

npx freellmapi setup-opencode --url http://localhost:3001

生成器写入全局 OpenCode 配置：

~/.config/opencode/opencode.json

freellmapi 提供程序与 @ai-sdk/openai 兼容包、基地址 http://localhost:3001/v1 以及实时目录中的模型地图一起出现在其中。默认模型变为 freellmapi/auto。

密钥本身不会出现在文件中：配置包含替换 {env:FREELLMAPI_API_KEY}。因此，当代理启动时，该变量必须保持设置状态：

opencode

这种方法也很方便，因为秘密不会出现在配置中，也不会出现在 git 中。对于 CI 和一次性运行，这比将密钥存储在文件中更正确。

手动设置

如果您不想运行生成器，可以在 opencode.json 中手动描述提供程序。最小选项如下所示：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "freellmapi/auto",
  "provider": {
    "freellmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "FreeLLMAPI",
      "options": {
        "baseURL": "http://localhost:3001/v1",
        "apiKey": "{env:FREELLMAPI_API_KEY}"
      },
      "models": {
        "auto": {
          "name": "FreeLLMAPI Auto Router",
          "limit": { "context": 1048576, "output": 65536 }
        }
      }
    }
  }
}

顶层的模型字段很重要：没有它，OpenCode 可能会继续使用以前的模型，或者在全新安装时不选择任何内容。最好从网关响应中获取上下文和输出限制，而不是发明它们：

curl http://localhost:3001/v1/models

如果需要手动切换到模型列表，您可以将特定标识符添加到模型列表中。但对于日常工作，自动就足够了：路由器本身会选择一个实时模型，并在达到限制时进行切换。

如何使用

启动 opencode 后，模型列表将使用熟悉的命令打开：

/models

它将有一个 FreeLLMAPI 提供程序和一个自动模型。然后工作照常进行：我们描述任务，通过@指定文件，用Tab键切换计划模式，用/undo命令回滚编辑。对于新项目，运行 /init 以使代理创建 AGENTS.md 非常有用。

一些实用技巧：

  • 路由。对于例行程序，请将其保留为自动。如果您需要速度，请尝试 auto:fast，如果质量是 auto:smart 或目录中的特定强大型号。
  • 诊断 每个网关响应都包含一个 X-Roated-Via 标头，其中包含实际为请求提供服务的提供商和模型的名称。它显示路由器将任务发送到的位置。
  • 分析。在“分析”页面上，面板显示请求量、成功、p50/p95 延迟以及提供商的令牌消耗量。
  • 对话的连续性。在对话过程中切换模型时，网关可以添加有关上下文传输的简短注释。通过变量 FREELLMAPI_CONTEXT_HANDOFF=on_model_switch 启用。

如果 OpenCode 在容器中运行并且 FreeLLMAPI 在主机上运行，​​则 localhost 将指向容器本身。在这种情况下，您需要使用 host.docker.internal 或可从 baseURL 中的容器访问的其他地址。

需要注意什么

FreeLLMAPI 不是付费模型的替代品，也不是具有 SLA 的服务。这是一种将免费计划捆绑到一个简洁网关中的方法。因此有几个限制：

  • 质量波动。免费关税结束，到了晚上，接近每日配额耗尽时，路由器可能会切换到较弱的型号。配额通常会在 UTC 午夜重置。
  • 延迟是可变的。不同的提供商响应不同，切换到备份模型时，请求可能需要明显更长的时间。
  • 没有旗舰型号。免费计划中提供不错但不是高端的型号。对于复杂的架构，这是值得考虑的。
  • 网关必须正在运行。如果应用程序或容器停止，OpenCode 将不会收到响应。自动启动托盘中的应用程序或重新启动容器策略可以解决此问题。
  • 该项目是为一个用户设计的。提供商密钥在本地存储并加密，但多人共享面板不适合此工具。应以与常规机密相同的方式保护统一密钥和 .env。

还有一个细微差别：模型目录会自行更新，但免费安装会延迟大约三十天收到目录快照。高级付费计划可以加快更新速度，但不需要熟悉该项目 – 路由器本身仍然免费且开放。

链接

https://github.com/tashfeenahmed/freellmapi
https://freellmapi.co/
https://freellmapi.co/models
https://github.com/tashfeenahmed/freellmapi/releases/latest
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md
https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md
https://opencode.ai/
https://opencode.ai/docs/
https://opencode.ai/docs/providers/

来源

https://github.com/tashfeenahmed/freellmapi
https://github.com/tashfeenahmed/freellmapi/blob/main/README.ru.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/install/01-install.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/01-agent-clients.md
https://github.com/tashfeenahmed/freellmapi/blob/main/docs/en/clients/02-supported-agents.md
https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md
https://opencode.ai/docs/providers/

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts

DemensDeum
Powered by  GDPR Cookie Compliance (opens in a new tab)
Privacy Overview

This website uses cookies so that we can provide you with the best user experience possible. Cookie information is stored in your browser and performs functions such as recognising you when you return to our website and helping our team to understand which sections of the website you find most interesting and useful.