# 向后兼容性

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

为帮助您更稳妥地集成和使用方舟 API，本文介绍方舟关于向后兼容性的通用说明，以及建议采用的客户端适配方式。

## 适用范围

本说明适用于以下对象：

* REST API。
* 方舟官方 SDK。
* 模型系列。

## 兼容性说明

方舟会尽量避免在同一主版本中引入不兼容的接口变更，以降低协议演进对存量接入的影响。

模型输出和提示词行为本身具有不确定性，不同模型版本之间的提示词行为和模型表现可能发生变化。如需获得更稳定的模型输出，建议固定模型版本，并结合实际业务场景进行评测与验证。

## 常见的向后兼容变更

以下变更通常属于向后兼容的变更：

* 新增 API 接口。
* 新增可选的请求参数。
* 在 JSON 响应对象或事件数据中新增字段。
* 调整 JSON 响应对象中字段的返回顺序。
* 调整资源标识等不透明字符串的长度或格式。
* 在流式 API 中新增事件类型。

## 客户端适配建议

为更好地开发后续演进，建议您在客户端开发中遵循以下原则：

* 对响应内容采用宽松解析策略，忽略未识别字段；如非业务必需，不建议对整个响应 JSON 做强校验。
* 对枚举类型字段保留未知值兼容能力，避免因新增取值直接报错。
* 仅传递业务必需的请求参数，不依赖未文档化的参数或行为。
* 基于 HTTP 状态码、错误码等稳定结构处理错误，不依赖错误消息的具体文案。
* 不依赖 JSON 字段顺序，以及资源标识等不透明字符串的固定长度或固定格式。

## 变更说明渠道

如有兼容性相关更新，请以官方文档中的 [产品更新公告](/docs/product-update-announcements)、[模型发布公告](/docs/model-release-announcement) 和 [模型下线公告](/docs/model-deprecation-notice) 等信息为准。