跳转至

开发者快速入门

本指南解释了如何通过社区代理向 Gonka 发送推理请求。这是今天开始使用网络的最快方式。如果您希望运行自己的网关而非通过代理，请参见本页底部的“运行您的网关”。想自己作为代理运营？请参见有兴趣运营网关吗？ - 从 OpenBroker 开始，如果 OpenBroker 无法满足您的需求，可使用 GitHub 白名单问题作为备选方案。

如何连接到 Gonka

Gonka 推理现在围绕 devshards 组织——短暂的会话，持有小额链上存款（托管资金），并离线按请求结算。打开 devshard、签署请求、轮换会话以及向链提交结算的角色由一种称为 网关 的软件执行。

对于大多数开发者而言，使用 Gonka 最简单的方式是调用 社区代理——第三方通过网关提供推理访问，并暴露标准的 OpenAI 兼容 API。您只需从代理获取一个 API 密钥即可。

Gonka 与传统 AI API 的区别

Gonka 不仅仅是一个 AI API。它是一种用于可证明推理的加密协议，旨在使模型执行、计费和结算独立可审计，而非完全由单一提供商控制。

方面 传统 AI API
(OpenAI, Anthropic 等)		 Gonka API
模型来源与可验证输出 模型由提供商托管和版本化，但用户无法独立验证哪个模型生成了特定输出。 推理可链接到协议定义的模型元数据和网络执行记录，实现可验证的来源。
抗审查性 访问由提供商集中控制。 访问正转向透明的协议治理机制。当前生产访问仍受保护，协议级请求验证正在完成中。
可审计性与透明度 日志记录、计费和使用跟踪由 API 提供商控制。 请求、计费和结算设计为可签名、带时间戳且可审计。
透明的代币经济 定价和资源分配由提供商定义。 网络的每次推理价格和结算由协议定义并上链，使底层推理经济可检查。

使用社区代理（推荐）

代理是独立运营者，运行 Gonka 网关并向开发者转售推理服务。从您的应用程序角度看，代理端点的行为与任何 OpenAI 兼容 API 相同：您设置 base_url，传递 Authorization: Bearer <API_KEY> 头部，并像往常一样调用 /v1/chat/completions。

代理不属于核心协议

代理是独立的第三方。定价、支付方式（美元、加密货币、积分）、速率限制、支持的模型、SLA、退款政策和数据处理均由每个代理自行决定。上线前请阅读代理的文档和条款。

1.1 选择一个代理

关于此列表

这是一个精选的社区代理目录，它们通过公共 Gonka 网关路由推理，并同意公开列示。该列表不完整，也不对任何运营者背书。列表在每次页面加载时随机排序，因此每个代理的位置并非排名；请独立评估每个运营者。此目录反映了早期启动集。想自己成为代理吗？ 使用 OpenBroker（参见 §3），如果 OpenBroker 无法满足您的需求，可作为备选方案打开 GitHub 白名单问题。部分代理提供 ▶ 演示 链接，指向简短的入门录屏——风格和长度可能有所不同。

比较代理——社区可观测性仪表板

社区成员对公共代理端点运行独立的监控探针并发布结果。这些仪表板可帮助您在选择代理前比较正常运行时间、延迟和价格：

这些仪表板是社区构建的工具，不属于核心协议的一部分。数据准确性、方法和可用性由每个仪表板运营商负责。请始终通过您自己的测试验证关键指标。每次页面加载时，列表均随机显示。

1.2 获取 API 密钥

遵循代理网站上的入门说明。通常，您需要：

  1. 在代理网站上注册（邮箱、账户、账单设置）。
  2. 在代理的仪表板中生成 API 密钥。
  3. 记录代理的 base_url（例如 https://api.<broker-domain>/v1）以及支持的模型列表。

1.3 连接无代码应用或 AI 编程助手

将您的 API 密钥插入几乎任何支持 OpenAI 兼容提供商的 AI 软件、聊天界面或代理框架。

您需要从代理处获取三项信息（参见 §1.2）：基础 URL、您的 API 密钥 和 模型 ID。

在大多数应用中，映射关系如下：

应用中的字段 应输入的内容
API 基础 URL / 端点 您的代理 URL 加上 /v1，例如 https://<broker-url>/v1。如果应用要求提供 "OpenAI 基础 URL" 或 "自定义端点"，这就是它。
API 密钥 / 认证令牌 您生成的密钥。即使应用提示 "输入 OpenAI API 密钥"，也请在此处使用您的代理密钥。
模型 / 自定义模型 您的代理支持的确切模型 ID。模型 ID 区分大小写——请完全复制，例如 MiniMaxAI/MiniMax-M2.7。

不同应用版本中的确切菜单名称可能有所不同——请查找等效设置。

示例：Open WebUI、LibreChat、LobeChat。

进入 设置 → AI 提供商 / 连接，选择 OpenAI 提供商，将默认的 OpenAI URL 替换为您的代理 URL 加上 /v1，插入您的密钥，并将模型 ID 添加到允许的模型列表中。

示例：Cursor、Cline、Windsurf。

进入 设置 → 模型，启用 OpenAI 兼容 提供商（或 添加自定义模型），将基础 URL 覆盖为您的代理 URL 加上 /v1，并粘贴您的代理 API 密钥。

示例：Make.com、n8n、Flowise。

使用标准的 OpenAI 模块，然后查找高级设置以将 基础路径 / 基础 URL 覆盖为您的代理 URL。

更倾向于编写代码？请继续阅读 §1.4 在 Gonka 上发送您的第一个请求。

1.4 在 Gonka 上发送您的第一个请求

设置环境变量：

export GONKA_BROKER_URL=<broker-base-url>     # e.g. https://api.example-broker.com/v1
export GONKA_BROKER_API_KEY=<your-api-key>
export GONKA_MODEL=MiniMaxAI/MiniMax-M2.7   # or any model your broker supports

Gonka 代理与 OpenAI 兼容，因此您可以直接使用官方 OpenAI SDK——无需使用 Gonka 特定客户端。

安装 OpenAI Python SDK：

```bash
pip install openai
```

创建 `example.py`：

```py linenums="1"
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["GONKA_BROKER_URL"],
    api_key=os.environ["GONKA_BROKER_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["GONKA_MODEL"],
    messages=[
        {"role": "user", "content": "Write a one-sentence bedtime story about a unicorn"}
    ],
)

print(response.choices[0].message.content)
```

使用 `python example.py` 运行。

安装 OpenAI JS SDK：

```bash
npm install openai
```

创建 `example.mjs`：

```ts linenums="1"
import OpenAI from "openai";

const client = new OpenAI({
    baseURL: process.env.GONKA_BROKER_URL,
    apiKey: process.env.GONKA_BROKER_API_KEY,
});

const response = await client.chat.completions.create({
    model: process.env.GONKA_MODEL,
    messages: [{ role: "user", content: "Hello! Tell me a short joke." }],
});

console.log(response.choices[0].message.content);
```

使用 `node example.mjs` 运行。

使用官方 openai-go 客户端：

```go linenums="1"
package main

import (
    "context"
    "log"
    "os"

    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
)

func main() {
    client := openai.NewClient(
        option.WithBaseURL(os.Getenv("GONKA_BROKER_URL")),
        option.WithAPIKey(os.Getenv("GONKA_BROKER_API_KEY")),
    )

    r, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
        Model: os.Getenv("GONKA_MODEL"),
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage("Write a haiku about programming"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Println(r.Choices[0].Message.Content)
}
```

片刻后，您应该会在终端中看到推理响应。

1.5 工具调用

工具调用通过相同的 OpenAI 兼容端点支持。仅 type: "function" 受支持 — Gonka 在底层使用 vLLM，它实现了 OpenAI 聊天完成规范，而非 Assistants API（code_interpreter、file_search 不可用）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import os
import json
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["GONKA_BROKER_URL"],
    api_key=os.environ["GONKA_BROKER_API_KEY"],
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name"}
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model=os.environ["GONKA_MODEL"],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message
if message.tool_calls:
    call = message.tool_calls[0]
    args = json.loads(call.function.arguments)
    print(call.function.name, args)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import OpenAI from "openai";

const client = new OpenAI({
    baseURL: process.env.GONKA_BROKER_URL,
    apiKey: process.env.GONKA_BROKER_API_KEY,
});

const tools = [
    {
        type: "function",
        function: {
            name: "get_weather",
            description: "Get the current weather for a city",
            parameters: {
                type: "object",
                properties: { city: { type: "string", description: "City name" } },
                required: ["city"],
            },
        },
    },
];

const response = await client.chat.completions.create({
    model: process.env.GONKA_MODEL,
    messages: [{ role: "user", content: "What's the weather in Paris?" }],
    tools,
    tool_choice: "auto",
});

const message = response.choices[0].message;
if (message.tool_calls) {
    const call = message.tool_calls[0];
    const args = JSON.parse(call.function.arguments);
    console.log(call.function.name, args);
}

运行您自己的网关（高级）

如果您需要自己操作链上 Gonka 网关（您自己的允许列表钱包、您自己的托管金、直接 GNK 结算），您可以在自己的机器或服务器上运行网关软件——绝不能在 Gonka 主机上运行。它暴露与代理相同的 OpenAI 兼容 API，但您拥有密钥，并直接在链上为它创建的 devshards 支付 GNK。

大多数操作者应通过 OpenBroker 成为代理

OpenBroker 不仅仅是目录中的“另一个代理”。 它是由可信社区成员创建和运营的基础设施，使您能够成为代理——创建代理账户、充值 GNK、颁发 API 密钥并提供推理服务——无需链上允许列表的创建者地址，也无需运行您自己的网关。

除非您明确需要自托管的允许列表网关，否则请优先选择 §3（OpenBroker）。

自托管网关需要允许列表地址

目前，只有链上 devshard_escrow_params.allowed_creator_addresses 列表中的 Gonka 账户才能打开 devshards。如果您的地址不在该列表中，您的网关无法创建会话，也无法发送推理请求。允许列表仅通过链上治理投票更改。参见有兴趣操作网关？ —— 从 OpenBroker 开始，或在 OpenBroker 无法满足您的需求时使用 GitHub 允许列表问题作为备选方案。

完整部署说明请参见 运行您自己的网关。

有兴趣操作网关？

推理通过网关进入网络。如果您想成为代理/为自己或您的用户操作推理访问，请选择以下路径。

推荐 - 通过 OpenBroker 成为代理

OpenBroker (openbroker.gonka.gg) 是成为代理的推荐方式。

它是由可信社区成员创建和运营的代理控制平面：您注册一个代理账户，存入 GNK，生成 API 密钥，并提供 OpenAI 兼容端点。OpenBroker 为您运行允许列表的托管金和 devshard 生命周期——您无需将您的地址列入 allowed_creator_addresses。

高级 - 运行您自己的链上网关

仅当 OpenBroker 无法满足您的需求时（例如您必须自行持有托管金密钥，或需要自定义链上设置），才运行您自己的 gonka-mainnet 网关。这要求您的地址在治理控制的允许列表中（devshard_escrow_params.allowed_creator_addresses）。完整说明请参见网关指南。

备选 - GitHub 允许列表请求

如果 OpenBroker 无法满足您的需求，且您仍需要自托管网关的允许列表创建者地址，请作为备选方案打开一个 GitHub 问题。

请包含您的操作者名称和联系方式、您打算使用的 gonka1... 地址以及您计划提供的模型。是否列入列表由链上治理决定——任何单一操作者或组织均无权单方面添加地址——表达兴趣不保证会被审核、列入或有明确时间表。

需要帮助？ 请参阅 FAQ 页面，或加入 Discord 服务器 以获取技术问题或安全问题的支持。