NewVFX API 开发者文档增加的cacle接口使用说明

该话题为空。

正在查看 0 条回复

作者
帖子

2026年10月6日 - 下午12:26 #1514

追光

管理员

下面这份可以直接作为 NewVFX API 开发者文档中的「流式任务与取消机制」章节。我把两种方式、完整请求示例、响应、前端/后端示例以及行为说明都整理进去，代码全部单独包裹。

NewVFX API 开发者文档

流式任务与取消机制

文档版本：1.0

一、概述

NewVFX API 的

/v1/chat/completions

支持标准的 HTTP 流式响应（SSE）。

开发者开启：

{
  "stream": true
}

后，服务器会持续返回生成内容。

在流式生成过程中，如果用户点击“停止生成”，开发者不需要等待模型生成结束，也不需要额外通知模型服务停止。

NewVFX 会将：

客户端主动断开流式连接

视为：

取消当前生成任务

服务器检测到客户端连接已经断开后，会自动终止当前上游请求，并停止继续消耗计算资源。

二、流式请求

开发者首先通过

/v1/chat/completions

创建流式任务。

请求地址

POST https://www.newvfx.com/v1/chat/completions

请求 Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求示例

curl -N -X POST \
'https://www.newvfx.com/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
  "model": "gemma-4",
  "messages": [
    {
      "role": "user",
      "content": "写一个科幻故事"
    }
  ],
  "stream": true
}'

三、获取 Request ID

每一次流式请求都有唯一的任务 ID。

服务器会通过 HTTP Response Header 返回：

X-NVFX-Request-ID: chatcmpl-xxxxxxxxxxxxxxxx

例如：

X-NVFX-Request-ID: chatcmpl-VLlMI9TWKlY2jSJeno74

开发者如果需要后续通过

/v1/cancel

主动取消任务，应保存这个 Request ID。

JavaScript 获取方式

const requestId = response.headers.get('X-NVFX-Request-ID');

console.log('NewVFX Request ID:', requestId);

Request ID 只对应当前这一次生成任务。

例如：

chatcmpl-A
chatcmpl-B
chatcmpl-C

分别代表三个独立任务。

四、方式一：断开流式连接即可取消

这是 NewVFX API 推荐的普通使用方式。

开发者不需要调用任何额外 API。

只需要关闭当前正在读取的 SSE / HTTP 流。

4.1 浏览器 Fetch 示例

let controller = null;

async function generate() {
    controller = new AbortController();

    try {
        const response = await fetch(
            'https://www.newvfx.com/v1/chat/completions',
            {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'Authorization': 'Bearer YOUR_API_KEY'
                },
                body: JSON.stringify({
                    model: 'gemma-4',
                    messages: [
                        {
                            role: 'user',
                            content: '写一个科幻故事'
                        }
                    ],
                    stream: true
                }),
                signal: controller.signal
            }
        );

        const reader = response.body.getReader();

        while (true) {
            const { done, value } = await reader.read();

            if (done) {
                break;
            }

            const chunk = new TextDecoder().decode(value);

            console.log(chunk);
        }

    } catch (error) {
        if (error.name === 'AbortError') {
            console.log('生成已停止');
        } else {
            console.error(error);
        }
    }
}

当用户点击停止按钮时：

function stopGeneration() {
    if (controller) {
        controller.abort();
        controller = null;
    }
}

调用：

controller.abort();

之后，浏览器会关闭当前 HTTP 请求。

NewVFX 检测到客户端连接断开后，会自动执行取消流程。

五、自动取消的服务器处理流程

当客户端断开连接后，NewVFX 内部执行：

客户端
    │
    │ SSE / HTTP Stream
    ▼
NewVFX API
    │
    │ 检测客户端连接
    ▼
connection_aborted()
    │
    │ = 1
    ▼
CLIENT_DISCONNECT
    │
    ▼
AUTO_CANCEL_TRIGGERED
    │
    ▼
写入 Cancel 状态
    │
    ▼
CURL_PROGRESS_CANCEL
    │
    ▼
终止上游 cURL
    │
    ▼
结束当前生成任务
    │
    ▼
任务状态：aborted

因此，开发者不需要实现额外的服务器轮询。

六、方式二：使用

/v1/cancel

主动取消

NewVFX 同时提供独立的取消接口。

这个接口主要用于：

开发者已经无法直接操作原始流式连接，但仍然希望通过 Request ID 取消指定任务。

请求地址

POST https://www.newvfx.com/v1/cancel

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求 Body

{
  "request_id": "chatcmpl-xxxxxxxxxxxxxxxx"
}

七、Cancel 请求示例

cURL

curl -X POST \
'https://www.newvfx.com/v1/cancel' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
  "request_id": "chatcmpl-xxxxxxxxxxxxxxxx"
}'

成功响应

{
  "ok": true,
  "request_id": "chatcmpl-xxxxxxxxxxxxxxxx",
  "scope": "api_stream",
  "message": "取消信号已发送"
}

八、JavaScript 主动取消示例

async function cancelGeneration(requestId) {
    if (!requestId) {
        return;
    }

    const response = await fetch(
        'https://www.newvfx.com/v1/cancel',
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Bearer YOUR_API_KEY'
            },
            body: JSON.stringify({
                request_id: requestId
            })
        }
    );

    const result = await response.json();

    console.log('Cancel result:', result);
}

调用：

await cancelGeneration(
    'chatcmpl-xxxxxxxxxxxxxxxx'
);

九、两种取消方式的区别

方式	使用方法	推荐场景
断开 SSE / HTTP	关闭当前流式连接	普通网页、App、SDK
`/v1/cancel`	根据 Request ID 主动取消	后台、异步系统、跨进程控制

对于普通流式聊天：

优先使用断开连接。

开发者无需为了停止生成而额外调用

/v1/cancel

。

十、推荐的网页应用实现

对于聊天网页，推荐使用：

开始生成
    ↓
创建 AbortController
    ↓
POST /v1/chat/completions
    ↓
保存 X-NVFX-Request-ID
    ↓
读取 SSE
    ↓
用户点击「停止」
    ↓
AbortController.abort()
    ↓
关闭 SSE
    ↓
NewVFX 自动取消

示例：

let controller = null;
let requestId = '';

async function sendMessage(message) {
    controller = new AbortController();
    requestId = '';

    try {
        const response = await fetch(
            'https://www.newvfx.com/v1/chat/completions',
            {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'Authorization': 'Bearer YOUR_API_KEY'
                },
                body: JSON.stringify({
                    model: 'gemma-4',
                    messages: [
                        {
                            role: 'user',
                            content: message
                        }
                    ],
                    stream: true
                }),
                signal: controller.signal
            }
        );

        requestId =
            response.headers.get('X-NVFX-Request-ID') || '';

        console.log(
            'Request ID:',
            requestId
        );

        const reader = response.body.getReader();
        const decoder = new TextDecoder();

        while (true) {
            const { done, value } =
                await reader.read();

            if (done) {
                break;
            }

            const chunk =
                decoder.decode(value, {
                    stream: true
                });

            // 处理 SSE 数据
            console.log(chunk);
        }

    } catch (error) {

        if (error.name === 'AbortError') {
            console.log('用户停止生成');
        } else {
            console.error(error);
        }

    } finally {
        controller = null;
        requestId = '';
    }
}

停止按钮：

function stopMessage() {
    if (!controller) {
        return;
    }

    controller.abort();
    controller = null;
    requestId = '';
}

十一、为什么不建议普通开发者同时调用两个取消接口

对于正常的浏览器流式请求：

POST /v1/chat/completions
        ↓
SSE
        ↓
用户点击停止
        ↓
AbortController.abort()

已经足够。

不建议设计成：

用户点击停止
        ↓
POST /v1/cancel
        ↓
AbortController.abort()

作为普通业务的强制流程。

原因是：

原始 HTTP 流本身就是当前任务的生命周期。
客户端断开后 NewVFX 会自动检测。
不需要额外增加一次 HTTP 请求。
可以减少前端取消逻辑。
可以避免 Cancel 请求与原始流同时关闭时产生竞态。

因此：

普通流式应用：断开即可。

十二、什么时候应该使用

/v1/cancel

以下场景可以使用独立 Cancel API：

场景 A：后台管理

后台管理员需要停止某个正在生成的任务。

管理后台
    ↓
request_id
    ↓
POST /v1/cancel
    ↓
取消指定任务

场景 B：异步任务系统

任务创建服务和任务控制服务不是同一个 HTTP 连接。

任务服务
    ↓
创建任务
    ↓
chatcmpl-XXXX
    ↓
任务控制服务
    ↓
POST /v1/cancel

场景 C：跨服务控制

一个服务负责创建任务，另一个服务负责取消任务。

这种情况下无法简单通过关闭原始 HTTP 连接实现控制，因此可以使用：

POST /v1/cancel

十三、Request ID 的重要性

Request ID 是单次生成任务的唯一标识。

例如：

chatcmpl-A
chatcmpl-B
chatcmpl-C

如果调用：

{
  "request_id": "chatcmpl-B"
}

只取消：

chatcmpl-B

不会取消：

chatcmpl-A
chatcmpl-C

因此开发者如果使用

/v1/cancel

，必须保存创建任务时返回的：

X-NVFX-Request-ID

十四、客户端断开后的任务状态

如果用户主动关闭流式连接，NewVFX 会将任务视为：

aborted

内部取消原因：

client_disconnect

例如服务器内部会产生类似：

AUTO_CANCEL_TRIGGERED
reason: client_disconnect

并终止当前上游请求。

因此开发者不应该把这种情况理解为：

模型生成失败

而应该理解为：

用户主动停止生成

十五、HTTP 499 的含义

客户端主动断开后，服务器内部可以将任务记录为：

HTTP 499

其含义是：

Client Closed Request

即：

客户端主动关闭了请求。

这与模型服务异常、网络错误、服务器错误不同。

例如：

表示正常完成。

表示客户端主动取消。

而：

4xx / 5xx

中的其他错误，则应根据具体错误类型进行处理。

十六、开发者实现原则

NewVFX 流式 API 的取消机制遵循以下原则：

原则 1

断开流 = 取消任务

原则 2

普通网页和 App 不需要调用

/v1/cancel

。

原则 3

需要远程控制指定任务时，可以使用：

POST /v1/cancel

原则 4

独立 Cancel 必须使用正确的：

request_id

原则 5

每个 Request ID 只对应一个生成任务。

十七、最终推荐

对于绝大多数开发者，只需要实现：

const controller =
    new AbortController();

发送：

fetch(
    'https://www.newvfx.com/v1/chat/completions',
    {
        signal: controller.signal
    }
);

用户点击停止：

controller.abort();

即可。

NewVFX 会自动完成：

客户端断开
→
检测断开
→
自动取消
→
中断上游请求
→
停止生成
→
任务记录 aborted

只有在无法直接关闭原始流式连接的高级应用中，才需要：

POST /v1/cancel

并提供：

{
  "request_id": "chatcmpl-xxxxxxxx"
}

API 速查

创建流式任务

POST https://www.newvfx.com/v1/chat/completions

获取任务 ID

X-NVFX-Request-ID: chatcmpl-xxxxxxxx

普通取消

直接关闭 SSE / HTTP 流

高级取消

POST https://www.newvfx.com/v1/cancel

请求：

{
  "request_id": "chatcmpl-xxxxxxxx"
}

取消后的内部状态

status: aborted
reason: client_disconnect

核心结论

NewVFX 流式 API：

客户端断开连接
        =
取消当前生成任务

这是普通开发者最简单、最推荐的使用方式。

作者
帖子

正在查看 0 条回复

在下方一键注册，登录后就可以回复啦。

NewVFX API 开发者文档增加的cacle接口使用说明

NewVFX API 开发者文档

流式任务与取消机制

一、概述

二、流式请求

请求地址

请求 Headers

请求示例

三、获取 Request ID

JavaScript 获取方式

四、方式一：断开流式连接即可取消

4.1 浏览器 Fetch 示例

五、自动取消的服务器处理流程

六、方式二：使用/v1/cancel 主动取消

请求地址

Headers

请求 Body

七、Cancel 请求示例

cURL

成功响应

八、JavaScript 主动取消示例

九、两种取消方式的区别

十、推荐的网页应用实现

十一、为什么不建议普通开发者同时调用两个取消接口

十二、什么时候应该使用/v1/cancel

场景 A：后台管理

场景 B：异步任务系统

场景 C：跨服务控制

十三、Request ID 的重要性

十四、客户端断开后的任务状态

十五、HTTP 499 的含义

十六、开发者实现原则

原则 1

原则 2

原则 3

原则 4

原则 5

十七、最终推荐

API 速查

创建流式任务

获取任务 ID

普通取消

高级取消

取消后的内部状态

核心结论

六、方式二：使用
`/v1/cancel`
主动取消

十二、什么时候应该使用
`/v1/cancel`