Co-Link：将多台设备整合为统一 AI API 的使用指南

![image.png](https://dl.playground.lazycat.cloud/guidelines/779/91b3df84-6c08-434c-93d3-1c2e82fddd37.png "image.png")



https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.colink



# 1. 使用流程概览

Co-Link 的使用可以拆分为三个步骤：

```text
1. 注册账号并获取 Token
2. 启动 Client（接入算力节点）
3. 调用 API（使用 AI 服务）
```

---

## 1.1 系统角色说明

| 角色      | 说明                 |
| ------- | ------------------ |
| Server  | 调度中心，负责路由请求（已部署完成） |
| Client  | 算力节点，执行推理任务        |
| API 调用者 | 使用 AI 接口的程序或用户     |

---

# 2. 访问地址说明

```text
控制台地址：
https://colink.${微服名称}.heiyu.space

API 地址：
https://colink.${微服名称}.heiyu.space/v1
```

---

# 3. 初始化账号与 Token

## 3.1 注册账号

访问 Web 控制台：

```text
https://colink.${微服名称}.heiyu.space
```

![image.png](https://dl.playground.lazycat.cloud/guidelines/779/7641b4f7-2d43-4934-b148-522496b6b879.png "image.png")

完成注册并登录。

---

## 3.2 获取 Token

在用户面板中获取：

| Token        | 用途     |
| ------------ | ------ |
| Client Token | 用于节点接入 |
| API Token    | 用于接口调用 |

![image.png](https://dl.playground.lazycat.cloud/guidelines/779/07ddec9e-7fcb-4431-b305-0a22645f1d5e.png "image.png")

---

# 4. 接入算力节点（Client）

每一台提供算力的机器都需要运行一个 Client。

---

## 4.1 创建配置文件（config.yaml）

```yaml
client_token: ""
server_url: "wss://colink.${微服名称}.heiyu.space/ws"
max_parallel: 3

providers:
  - type: "openai"
    api_key: ""
    base_url: ""
    models:
      - local: "deepseek-chat"
        server_mapping: "pro-model"
```

---

## 4.2 启动 Client

### CoLink Client 下载地址

#### 🍎 macOS

- Intel (amd64)  
  https://github.com/Jlan45/CoLinkPlan/releases/download/v1.0.1/colink-darwin-amd64.tar.gz

- Apple Silicon (arm64)  
  https://github.com/Jlan45/CoLinkPlan/releases/download/v1.0.1/colink-darwin-arm64.tar.gz


#### 🐧 Linux

- AMD64  
  https://github.com/Jlan45/CoLinkPlan/releases/download/v1.0.1/colink-linux-amd64.tar.gz

- ARM64  
  https://github.com/Jlan45/CoLinkPlan/releases/download/v1.0.1/colink-linux-arm64.tar.gz


下载完成之后解压后将文件放到到 `config.yaml`  同目录，然后启动客户端

**Linux**

```bash
./colink-client-linux-amd64
# or
./colink-client-linux-arm64
```

**MacOS**

```bash
./colink-client-darwin-amd64
# or
./colink-client-darwin-arm64
```

---

## 4.3 启动成功标志

出现如下日志表示连接成功：

```json
{"time":"2026-04-07T19:15:35.661511906+08:00","level":"INFO","msg":"Starting Co-Link Client","config":"config.yaml","server":"wss://colink.${微服名称}.heiyu.space/ws","max_parallel":3}
{"time":"2026-04-07T19:15:35.662237086+08:00","level":"INFO","msg":"Dialing server","url":"wss://colink.${微服名称}.heiyu.space/ws"}
{"time":"2026-04-07T19:15:35.707830345+08:00","level":"INFO","msg":"Connected to server successfully"}
```

---

# 5. 验证节点是否接入成功

登录控制台后访问：

```text
https://colink.${微服名称}.heiyu.space/nodes
```

如果看到节点在线，则说明接入成功。

![image.png](https://dl.playground.lazycat.cloud/guidelines/779/aee8ce44-79fc-4546-b9c9-b5080feda12e.png "image.png")

---

# 6. 调用 AI API

Co-Link 完全兼容 OpenAI API。

统一 API 入口为：

```text
https://colink.${微服名称}.heiyu.space/v1
```

---

## 6.1 Python 示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-colink-your-api-token",
    base_url="https://colink.${微服名称}.heiyu.space/v1",
)

resp = client.chat.completions.create(
    model="pro-model",
    messages=[{"role": "user", "content": "Hello!"}],
)

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

---

## 6.2 流式调用

```python
stream = client.chat.completions.create(
    model="pro-model",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

---

## 6.3 curl 示例

```bash
curl -X POST https://colink.${微服名称}.heiyu.space/v1/chat/completions \
  -H "Authorization: Bearer ${API Token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"pro-model",
    "messages":[{"role":"user","content":"Hello!"}]
  }'
```

**运行成功**

![image.png](https://dl.playground.lazycat.cloud/guidelines/779/7bc4002b-eb76-49cf-b13a-8f63d9a6a6da.png "image.png")

---

# 7. 核心配置说明

---

## 7.1 并发控制

```yaml
max_parallel: 3
```

表示该节点最多同时处理 3 个请求。

---

## 7.2 模型映射

```yaml
models:
  - local: "deepseek-chat"
    server_mapping: "pro-model"
```

说明：

* `local`：Provider 实际模型名称
* `server_mapping`：对外暴露的模型名称（API 调用使用）

---

# 8. 调度机制说明

Co-Link Server 会自动：

* 选择空闲节点处理请求
* 节点失败自动切换（最多 3 次）
* 出错节点封禁 60 秒