ContextChatCompletions-上下文缓存对话--火山方舟大模型服务平台-火山引擎

文档中心

导航

ContextChatCompletions-上下文缓存对话

最近更新时间：2025.01.09 16:39:03首次发布时间：2024.09.24 11:09:17

POST https://ark.cn-beijing.volces.com/api/v3/context/chat/completions

调用本接口，向大模型发起带上下文缓存的请求。在发起之前，您需要调用ContextCreate-创建上下文缓存，创建上下文缓存，并获取到缓存的ID。

API使用教程请参见上下文缓存（Context API）概述。

请求参数

请求体

注意

大部分字段与ChatCompletions-文本生成一致，除了下面参数：

messages：不支持最后一个元素的role设置为assistant。如使用session 缓存（mode设置为session）传入最新一轮对话的信息，无需传入历史信息。
tools：目前上下文缓存不支持 tools 字段。
context_id：增加的字段，指定本次请求使用哪个上下文缓存。

参数名称	类型	是否必填	默认值	描述	示例值
model	String	是	-	您创建的推理接入点 ID	ep-2024-
context_id	String	是	无	上下文缓存的ID，用于关联缓存的信息。	ctx-xxx
messages	Array of messages	是	-	历史对话的信息。如果使用的是session 缓存模式，只需传入最新信息即可，不需要传入历史消息（由上下文缓存读入）。如果使用的是前缀缓存模式，则不需要传入初始信息（即创建缓存时传入的信息）。 `{ "role":"user", "content": "给我讲个故事" }`	-
stream	Boolean	否	false	响应内容是否流式返回 `false`：模型生成完所有内容后一次性返回结果 `true`：按 SSE 协议逐块返回模型生成内容，并以一条 `data: [DONE]` 消息结束	false
stream_options	Array ofStreamOptionsParam	否	-	流式响应的选项。仅当 `stream: true` 时可以设置 `stream_options` 参数。	-
max_tokens	Integer	否	4096	注意模型回复最大长度（单位 token），取值范围为 [0, 4096]。输入 token 和输出 token 的总长度还受模型的上下文长度限制。	4096
stop	String or Array	否	-	模型遇到 `stop` 字段所指定的字符串时将停止继续生成，这个词语本身不会输出。最多支持 4 个字符串。	["你好", "天气"]
frequency_penalty	Float	否	0	频率惩罚系数。如果值为正，会根据新 token 在文本中的出现频率对其进行惩罚，从而降低模型逐字重复的可能性。取值范围为 [-2.0, 2.0]。	1
presence_penalty	Float	否	0	存在惩罚系数。如果值为正，会根据新 token 到目前为止是否出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。取值范围为 [-2.0, 2.0]。	1
temperature	Float	否	1	采样温度。控制了生成文本时对每个候选词的概率分布进行平滑的程度。取值范围为 [0, 1]。当取值为 0 时模型仅考虑对数概率最大的一个 token。较高的值（如 0.8）会使输出更加随机，而较低的值（如 0.2）会使输出更加集中确定。通常建议仅调整 `temperature` 或 `top_p` 其中之一，不建议两者都修改。	0.8
top_p	Float	否	0.7	核采样概率阈值。模型会考虑概率质量在 `top_p` 内的 token 结果。取值范围为 [0, 1]。当取值为 0 时模型仅考虑对数概率最大的一个 token。如 0.1 意味着只考虑概率质量最高的前 10% 的 token，取值越大生成的随机性越高，取值越低生成的确定性越高。通常建议仅调整 `temperature` 或 `top_p` 其中之一，不建议两者都修改。	0.8
logprobs	Boolean	否	false	是否返回输出 tokens 的对数概率。 `false`：不返回对数概率信息 `true`：返回消息内容中每个输出 token 的对数概率	false
top_logprobs	Integer	否	0	指定每个输出 token 位置最有可能返回的 token 数量，每个 token 都有关联的对数概率。仅当 `logprobs: true` 时可以设置 `top_logprobs` 参数，取值范围为 [0, 20]。	2
logit_bias	Map<String, Integer>	否	-	调整指定 token 在模型输出内容中出现的概率，使模型生成的内容更加符合特定的偏好。`logit_bias` 字段接受一个 map 值，其中每个键为词表中的 token ID（使用 tokenization 接口获取），每个值为该 token 的偏差值，取值范围为 [-100, 100]。 -1 会减少选择的可能性，1 会增加选择的可能性；-100 会完全禁止选择该 token，100 会导致仅可选择该 token。该参数的实际效果可能因模型而异。
~~tools~~	~~Object~~	否	-	暂时不支持。	-

响应参数

非流式调用

参数名称	子字段	类型	描述
id	-	String	一次 chat completion 接口调用的唯一标识。
choices	-	Array	本次 chat 结果列表。长度固定为 1。
	index	Integer	该元素在 choices 列表的索引。
	message	Object	模型输出的消息内容。
	finish_reason	String	模型生成结束原因： `stop`：正常生成结束。 `length` 触发最大 token 数量而结束。 `content_filter` ：模型输出被内容审核拦截。
	logprobs	Object	该输出结果的概率信息，其只有一个 `content` 字段，类型为 `Array`，表示 message 列表中每个元素 content token 的概率信息。 content 元素子字段说明如下： `token` [String]: 对应 token。 `logprob` [Number]：token 的概率。 `bytes` [Array]：表示 token 的 UTF-8 字节表示的整数列表。在字符由多个 token 表示，并且它们的字节表示必须组合以生成正确的文本表示的情况下（表情符号或特殊字符）非常有用。如果 token 没有 byte 表示，则可以为空。 `top_logprobs` [Array]：最可能的 token 列表及其在此 token 位置的对数概率： `token` [String]: 对应 token； `logprob` [Number]：token 的概率； `bytes` [Array]：表示 token 的 UTF-8 字节表示的整数列表。在字符由多个 token 表示，并且它们的字节表示必须组合以生成正确的文本表示的情况下（表情符号或特殊字符）非常有用。如果 token 没有 byte 表示，则可以为空。
created	-	Integer	本次对话生成的时间戳（秒）。
model	-	String	实际使用的模型名称和版本。
object	-	String	固定为 chat.completion。
usage	-	Object	本次请求的 token 用量。
	prompt_tokens	Integer	本次请求中输入的 token 数量。
	completion_tokens	Integer	模型生成的 token 数量。
	total_tokens	Integer	总的 token 数量。
	prompt_tokens_details	Object	prompt_tokens中命中上下文缓存的tokens数。需要开通上下文缓存功能，并创建缓存才会启用。 `"prompt_tokens_details": { "cached_tokens": 18 }`

流式调用

字段	子字段	类型	描述
id	-	String	一次 chat completion 接口调用的唯一标识，一次流式调用所有的 chunk 有相同的 id。
choices	-	Array	结果列表。长度固定为 1。如果设置了`stream_options: {"include_usage": true}`，则最后一个 chunk 的 choices 也为空列表。
	index	Integer	该元素在 choices 列表的索引。
	delta	Object	由流式模型响应的模型输出增量，示例如下。 `{ "role": "assistant", "content": " there", }`
	finish_reason	String	模型生成结束原因，`stop`表示正常生成结束，`length` 表示已经到了生成的最大 token 数量，content_filter 表示命中审核提前终止。
	logprobs	Object	该输出结果的概率信息，其只有一个 content 字段，类型为 array，表示 message 列表中每个元素 content token 的概率信息，content 元素子字段说明如下： `token` [String]: 对应 token； `logprob` [Number]：token 的概率； `bytes` [Array]：表示 token 的 UTF-8 字节表示的整数列表。在字符由多个 token 表示，并且它们的字节表示必须组合以生成正确的文本表示的情况下（表情符号或特殊字符）非常有用。如果 token 没有 byte 表示，则可以为空。 `top_logprobs` [Array]：最可能的 token 列表及其在此 token 位置的对数概率： `token` [String]: 对应 token； `logprob` [Number]：token 的概率； `bytes` [Array]：表示 token 的 UTF-8 字节表示的整数列表。在字符由多个 token 表示，并且它们的字节表示必须组合以生成正确的文本表示的情况下（表情符号或特殊字符）非常有用。如果 token 没有 byte 表示，则可以为空。
created	-	Integer	本次对话生成时间戳（秒）。
model	-	String	实际使用的模型名称和版本。
object	-	String	固定为 chat.completion.chunk。
usage	-	Object	本次请求的 token 用量。一个可选字段，仅当在请求中设置`stream_options: {"include_usage": true}`时才会出现。如果设置了它，除了最后一个 chunk 包含整个请求的 token 使用量外，其它 chunk 的 usage 都是 null。
	prompt_tokens	Integer	本次请求中输入的 token 数量。
	completion_tokens	Integer	模型生成的 token 数量。
	total_tokens	Integer	总的 token 数量。
	prompt_tokens_details	Object	prompt_tokens中命中上下文缓存的tokens数。 `"prompt_tokens_details": { "cached_tokens": 18 }`

请求示例

curl --location 'https://ark.cn-beijing.volces.com/api/v3/context/chat/completions' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "context_id": "<YOUR_CONTEXT_ID>",
    "model": "<YOUR_ENDPOINT_ID>",
    "messages":[
        {
            "role":"user",
            "content": "你好"
        }
    ]
}'

响应示例

{
  "id": "123xxxabc",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "doubao-pro-32k-241215",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "我是李雷",
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 4,
    "total_tokens": 32,
    "prompt_tokens_details": {
      "cached_tokens": 18
  }
}

错误处理

错误响应

本接口调用失败的返回结构和参数释义请参见返回结构文档。

错误码

本接口错误码请参见公共错误码文档。

状态码	错误类型	错误码	错误信息	含义
403	Forbidden	OperationDenied.InvalidState	The specified context is in invalid state: InProgress.Request ID: {id}	请求所关联的Context ID处于非空闲状态，不可调用。