# 流式输出

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

默认情况下，方舟 API 会在生成全部内容后，再通过单次 HTTP 响应返回结果。如果输出长内容，等待时间会较长。流式响应模式下，模型会持续发送已生成的数据片段，你可实时看到中间输出过程内容，方便立即开始处理或展示部分结果。

<span id="e9511cf7"></span>
# 效果与优势

|预览 |优势 |
|---|---|
|[视频](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/0b0ed47ec1b94b20a4f4966aa80130e6) |* **改善等待体验**：无需等待完整内容生成完毕，可立即处理过程内容。 | \
| |* **实时过程反馈**：多轮交互场景，实时了解任务当前的处理阶段。 | \
| |* **更高的容错性**：中途出错，也能获取到已生成内容，避免非流式输出失败无返回的情况。 | \
| |* **简化超时管理**：保持客户端与服务端的连接状态，避免复杂任务耗时过长而连接超时。 |

<span id="f1d9aa59"></span>
# 使用说明

<span id="aba1f93c"></span>
## 启用流式

通过配置 **stream** 为 `true`，来启用流式输出。

<span id="9346c907"></span>
## 示例代码

* Chat API 示例代码：

**选项：Curl**

```Bash
curl https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seed-2-1-pro-260915",
    "messages": [
        {
            "role": "user",
            "content": "常见的十字花科植物有哪些？"
        }
    ],
    "stream": true
  }'
```

**选项：Python**

```Python
import os
# Install SDK: python -m pip install --upgrade arkruntime
from arkruntime import Ark

client = Ark(
    # The base URL for model invocation
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    # Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
    api_key=os.getenv('ARK_API_KEY'),
)

completion = client.chat.completions.create(
    # Replace with Model ID
    model = "doubao-seed-2-1-pro-260915",
    messages=[
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
    stream=True,
)

# Ensure the connection is closed automatically to prevent connection leaks.
with completion:
    for chunk in completion:
        if chunk.choices[0].delta.content is not None:
            print(chunk.choices[0].delta.content, end="")
```

> **说明**
>
> `with completion `：当 with 代码块内出现异常时，会自动调用对象的 __exit__() 方法进行清理工作。当设置了max_tokens 等中断条件时，可避免socket层数据载满最终程序卡住。

**选项：Go**

```Go
package main

import (
	"context"
	"fmt"
	"io"
	"os"
	"github.com/volcengine/ark-runtime-go/arkruntime"
	"github.com/volcengine/ark-runtime-go/arkruntime/model/chat"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
		os.Getenv("ARK_API_KEY"),
		// The base URL for model invocation
        arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
	)

	ctx := context.Background()

	fmt.Println("----- standard request -----")
	req := &chat.ChatCompletionRequest{
		// Replace with Model ID
		Model: "doubao-seed-2-1-pro-260915",
		Messages: []chat.ChatCompletionRequestMessage{
			userMessage("常见的十字花科植物有哪些？"),
		},
		Stream: chat.NewOptBool(true),
	}

	// 调用 CreateChatCompletionStream 方法，而不要使用非流式调用的 CreateChatCompletion 方法，否则将无法获取流式响应。
	resp, err := client.CreateChatCompletionStream(ctx, req)
	if err != nil {
		fmt.Printf("standard chat error: %v", err)
		return
	}

	defer resp.Close()
	for {
		chunk, err := resp.Recv()
		if err == io.EOF {
			break
		}
		if err != nil {
			fmt.Printf("stream error: %v", err)
			break
		}
		fmt.Print(chunk.Choices[0].Delta.Content.Or(""))
	}
	fmt.Println()
}

func userMessage(content string) chat.ChatCompletionRequestMessage {
	return chat.ChatCompletionRequestMessage{
		OneOf: chat.NewChatCompletionRequestUserMessageChatCompletionRequestMessageSum(
			chat.ChatCompletionRequestUserMessage{
				Role:    chat.ChatCompletionRequestUserMessageRoleUser,
				Content: chat.NewOptNilChatCompletionMessageContent(chat.NewStringChatCompletionMessageContent(content)),
			},
		),
	}
}
```

**选项：Java**

```Java
package com.volcengine.ark.runtime;

import com.volcengine.ark.runtime.models.chat.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.ArrayList;
import java.util.List;

public class ChatCompletionsExample {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        // The base URL for model invocation
        ArkService service = ArkService.builder().apiKey(apiKey)
                .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
                .build();
        final List<ChatCompletionRequestMessage> messages = new ArrayList<>();
        final ChatCompletionRequestMessage userMessage = ChatCompletionRequestUserMessage.builder().role(ChatCompletionRequestMessageType.USER).content(ChatCompletionMessageContent.ofString("常见的十字花科植物有哪些？")).build();
        messages.add(userMessage);

        ChatCompletionRequest chatCompletionRequest = ChatCompletionRequest.builder()
               .model("doubao-seed-2-1-pro-260915")//Replace with Model ID
               .messages(messages)
               .stream(true)
               .thinking(Thinking.builder().type(ThinkingMode.DISABLED).build())
               .build();
        service.streamChatCompletion(chatCompletionRequest)
               .doOnError(Throwable::printStackTrace) // 处理错误
               .blockingForEach(response -> {
                    if (response.getChoices() != null && !response.getChoices().isEmpty()) {
                        String content = String.valueOf(response.getChoices().get(0).getDelta().getContent());
                        if (content != null) {
                            System.out.print(content); // 注意用print而非println，保持内容连续
                        }
                    }
                });
        // shutdown service
        service.shutdownExecutor();
    }
}
```

**选项：OpenAI SDK**

```Python
import os
from openai import OpenAI

client = OpenAI(
    # Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
    api_key=os.environ.get("ARK_API_KEY"),
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    )

completion = client.chat.completions.create(
    # Replace with Model ID
    model = "doubao-seed-2-1-pro-260915",
    messages=[
        {"role": "user", "content": "常见的十字花科植物有哪些？"},
    ],
    stream=True,
)

# Ensure the connection is closed automatically to prevent connection leaks.
with completion:
    for chunk in completion:
        if chunk.choices[0].delta.content is not None:
            print(chunk.choices[0].delta.content, end="")
```

* Responses API 示例代码：

**选项：Curl**

```Bash
curl https://ark.cn-beijing.volces.com/api/v3/responses \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "doubao-seed-2-1-pro-260915",
      "input": "常见的十字花科植物有哪些？",
      "stream": true
  }'
```

**选项：Python**

```Python
import os
from arkruntime import Ark
from arkruntime.types.responses.response_completed_event import ResponseCompletedEvent
from arkruntime.types.responses.response_reasoning_summary_text_delta_event import ResponseReasoningSummaryTextDeltaEvent
from arkruntime.types.responses.response_output_item_added_event import ResponseOutputItemAddedEvent
from arkruntime.types.responses.response_text_delta_event import ResponseTextDeltaEvent
from arkruntime.types.responses.response_text_done_event import ResponseTextDoneEvent

# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key = os.getenv('ARK_API_KEY')

client = Ark(
    base_url='https://ark.cn-beijing.volces.com/api/v3',
    api_key=api_key,
)

# Create a request
response = client.responses.create(
    model="doubao-seed-2-1-pro-260915",
    input="常见的十字花科植物有哪些？",
    stream=True
)

for event in response:
    if isinstance(event, ResponseReasoningSummaryTextDeltaEvent):
        print(event.delta, end="")
    if isinstance(event, ResponseOutputItemAddedEvent):
        print("\noutPutItem " + event.type + " start:")
    if isinstance(event, ResponseTextDeltaEvent):
        print(event.delta,end="")
    if isinstance(event, ResponseTextDoneEvent):
        print("\noutPutTextDone.")
    if isinstance(event, ResponseCompletedEvent):
        print("Response Completed. Usage = " + event.response.usage.model_dump_json())
```

**选项：Go**

```Go
package main

import (
    "context"
    "fmt"
    "io"
    "os"

    "github.com/volcengine/ark-runtime-go/arkruntime"
    "github.com/volcengine/ark-runtime-go/arkruntime/model/responses"
)

func main() {
    client := arkruntime.NewClientWithApiKey(
        // Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
        os.Getenv("ARK_API_KEY"),
        arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
    )
    ctx := context.Background()

    resp, err := client.CreateResponsesStream(ctx, &responses.ResponsesRequest{
        Model:    "doubao-seed-2-1-pro-260915",
        Input:    responses.NewStringResponsesInput("常见的十字花科植物有哪些？"),

    })
    if err != nil {
        fmt.Printf("stream error: %v", err)
        return
    }
    for {
        event, err := resp.Recv()
        if err == io.EOF {
            break
        }
        if err != nil {
            fmt.Printf("stream error: %v", err)
            return
        }
        handleEvent(event)
    }
}
func handleEvent(event *responses.ResponseStreamEvent) {
    switch event.OneOf.Type {
    case responses.ResponseReasoningSummaryTextDeltaEventResponseStreamEventSum:
        print(event.OneOf.ResponseReasoningSummaryTextDeltaEvent.Delta.Or(""))
    case responses.ResponseReasoningSummaryTextDoneEventResponseStreamEventSum:
        fmt.Printf("\nAggregated reasoning text: %s\n", event.OneOf.ResponseReasoningSummaryTextDoneEvent.Text.Or(""))
    case responses.ResponseTextDeltaEventResponseStreamEventSum:
        print(event.OneOf.ResponseTextDeltaEvent.Delta.Or(""))
    case responses.ResponseTextDoneEventResponseStreamEventSum:
        fmt.Printf("\nAggregated output text: %s\n", event.OneOf.ResponseTextDoneEvent.Text.Or(""))
    }
}
```

**选项：Java**

```Java
package com.ark.example;
import com.volcengine.ark.runtime.service.ArkService;
import com.volcengine.ark.runtime.models.responses.*;
public class demo {
    public static void main(String[] args) {
        String apiKey = System.getenv("ARK_API_KEY");
        // The base URL for model invocation
        ArkService arkService = ArkService.builder().apiKey(apiKey)
                .baseUrl("https://ark.cn-beijing.volces.com/api/v3")
                .build();

        ResponsesRequest request = ResponsesRequest.builder()
                .model("doubao-seed-2-1-pro-260915")
                .stream(true)
                .input(ResponsesInput.ofString("常见的十字花科植物有哪些？"))

                .build();
        arkService.streamResponse(request)
            .doOnError(Throwable::printStackTrace)
            .blockingForEach(event -> {
                if (event instanceof ResponseReasoningSummaryTextDeltaEvent) {
                    System.out.print(((ResponseReasoningSummaryTextDeltaEvent) event).getDelta());
                }
                if (event instanceof ResponseOutputItemAddedEvent) {
                    System.out.println("OutputItem " + (((ResponseOutputItemAddedEvent) event).getItem().getType()) + " Start: ");
                }
                if (event instanceof ResponseTextDeltaEvent) {
                    System.out.print(((ResponseTextDeltaEvent) event).getDelta());
                }
                if (event instanceof ResponseTextDoneEvent) {
                    System.out.println("OutputText End.");
                }
                if (event instanceof ResponseOutputItemDoneEvent) {
                    System.out.println("OutputItem " + ((ResponseOutputItemDoneEvent) event).getItem().getType() + " End.");
                }
                if (event instanceof ResponseFunctionCallArgumentsDoneEvent) {
                    System.out.println("FunctionCall Arguments: " + ((ResponseFunctionCallArgumentsDoneEvent) event).getArguments());
                }
                if (event instanceof ResponseCompletedEvent) {
                    System.out.println("Response Completed. Usage = " + ((ResponseCompletedEvent) event).getResponse().getUsage());
                }
            });

        arkService.shutdownExecutor();
    }
}
```

**选项：OpenAI SDK**

```Python
import os
from openai import OpenAI

# Get API Key: https://ark.volcengine.com/region:cn-beijing/apikey
api_key = os.getenv('ARK_API_KEY')

client = OpenAI(
    base_url='https://ark.cn-beijing.volces.com/api/v3',
    api_key=api_key,
)

# Create a request
response = client.responses.create(
    model="doubao-seed-2-1-pro-260915",
    input="常见的十字花科植物有哪些？",
    stream=True
)

for event in response:
    if event.type == "response.reasoning_summary_text.delta":
        print(event.delta, end="")
    if event.type == "response.output_item.added":
        print("\noutPutItem " + event.type + " start:")
    if event.type == "response.output_text.delta":
        print(event.delta,end="")
    if event.type == "response.output_item.done":
        print("\noutPutTextDone.")
    if event.type == "response.completed":
        print("\nResponse Completed. Usage = " + event.response.usage.model_dump_json())
```

<span id="70213630"></span>
## 返回示例

流式响应基于**Server-Sent Events (SSE)** 协议实现，其核心是服务端通过HTTP长连接持续向客户端推送数据片段。每个数据片段（Chunk）由**字段行**组成。包括模型深度思考内容片段、回复内容片段、工具调用片段等。流式响应结束时，服务端会推送一个特殊片段，通常包含 `data: [DONE]`

**选项：Chat API**

```
data: {"choices":[{"delta":{"content":"","reasoning_content":"\n","role":"assistant"},"index":0}],"created":1765713048,"id":"021765713047481dd742fe08f96381a9e3cd447cf1b9ac3192379","model":"doubao-seed-2-1-pro-260628","service_tier":"default","object":"chat.completion.chunk","usage":null}
data: {"choices":[{"delta":{"content":"","reasoning_content":"用户","role":"assistant"},"index":0}],"created":1765713048,"id":"021765713047481dd742fe08f96381a9e3cd447cf1b9ac3192379","model":"doubao-seed-2-1-pro-260628","service_tier":"default","object":"chat.completion.chunk","usage":null}
...
data: {"choices":[{"delta":{"content":"","reasoning_content":"。","role":"assistant"},"index":0}],"created":1765713048,"id":"021765713047481dd742fe08f96381a9e3cd447cf1b9ac3192379","model":"doubao-seed-2-1-pro-260628","service_tier":"default","object":"chat.completion.chunk","usage":null}
data: {"choices":[{"delta":{"content":"你","role":"assistant"},"index":0}],"created":1765713048,"id":"021765713047481dd742fe08f96381a9e3cd447cf1b9ac3192379","model":"doubao-seed-2-1-pro-260628","service_tier":"default","object":"chat.completion.chunk","usage":null}
data: {"choices":[{"delta":{"content":"✧","role":"assistant"},"index":0}],"created":1765713048,"id":"021765713047481dd742fe08f96381a9e3cd447cf1b9ac3192379","model":"doubao-seed-2-1-pro-260628","service_tier":"default","object":"chat.completion.chunk","usage":null}
...
data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":"stop","index":0}],"created":1765713048,"id":"021765713047481dd742fe08f96381a9e3cd447cf1b9ac3192379","model":"doubao-seed-2-1-pro-260628","service_tier":"default","object":"chat.completion.chunk","usage":null}
data: [DONE]
```

返回格式说明：(具体字段参见[Chat API](/docs/chat-api))
* `choices[0].delta.content`: 模型生成的消息内容。
* `choices[0].delta.reasoning_content`: 模型思考内容。
* `choices[0].finish_reason`: 模型停止生成 token 的原因。（仅在最后一个chunk中出现）

**选项：Responses API**

```
event: response.created
data: {"type":"response.created","response":{"created_at":1764229579,"id":"resp_021764229578658fe9a0f6cb2cc6c828e7a59adbdb971872aee70","max_output_tokens":32768,"model":"doubao-seed-2-1-pro-260628","object":"response","thinking":{"type":"enabled"},"service_tier":"default","caching":{"type":"disabled"},"store":true,"expire_at":1764488778},"sequence_number":0}

event: response.in_progress
data: {"type":"response.in_progress","response":{"created_at":1764229579,"id":"resp_021764229578658fe9a0f6cb2cc6c828e7a59adbdb971872aee70","max_output_tokens":32768,"model":"doubao-seed-2-1-pro-260628","object":"response","thinking":{"type":"enabled"},"service_tier":"default","caching":{"type":"disabled"},"store":true,"expire_at":1764488778},"sequence_number":1}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"rs_02176422957963700000000000000000000ffffac15dd335c9c43","type":"reasoning","status":"in_progress"},"sequence_number":2}

event: response.reasoning_summary_part.added
data: {"type":"response.reasoning_summary_part.added","item_id":"rs_02176422957963700000000000000000000ffffac15dd335c9c43","output_index":0,"summary_index":0,"part":{"type":"summary_text"},"sequence_number":3}

event: response.reasoning_summary_text.delta
data: {"type":"response.reasoning_summary_text.delta","summary_index":0,"delta":"\n","item_id":"rs_02176422957963700000000000000000000ffffac15dd335c9c43","output_index":0,"sequence_number":4}
...
event: response.completed
data: {"type":"response.completed","response":{"created_at":1768809358,"id":"resp_021768809358289649f4507e5505b181d56acee99f33e5a9f1075","max_output_tokens":32768,"model":"doubao-seed-2-1-pro-260628","object":"response","output":[{"id":"rs_02176880935899200000000000000000000ffffac154346d65c7e","type":"reasoning","summary":[{"type":"summary_text","text":"\n..."}],"status":"completed"},{"type":"message","role":"assistant","content":[{"type":"output_text","text":"..."}],"status":"completed","id":"msg_02176880937345100000000000000000000ffffac154346bd6748"}],"service_tier":"default","status":"completed","usage":{"input_tokens":42,"output_tokens":846,"total_tokens":888,"input_tokens_details":{"cached_tokens":0},"output_tokens_details":{"reasoning_tokens":408}},"caching":{"type":"disabled"},"store":true,"expire_at":1769068558},"sequence_number":851}

data: [DONE]
```

返回示例说明：（具体字段参见 [Responses API](/docs/create-model-responses-api)）
* event类型`response.reasoning_summary_text.delta`，`event.delta`为模型思考内容。
* event类型`response.output_text.delta`，`event.delta`为模型生成的消息内容。
* event类型`response.completed`，`event.response.usage`为本次请求的 token 用量。

<span id="e3f9c7c9"></span>
# API 文档

* [Chat API](/docs/chat-api)
* [Responses API](/docs/create-model-responses-api)

<span id="6a2d9c11"></span>
# 更多示例

* 函数调用流式输出，请参见 [流式输出](/docs/function-calling#ba983529)。