write-修改已有文件并自动刷新语义与向量--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

请输入

文件内容

write-修改已有文件并自动刷新语义与向量

概述

/api/v1/content/write 接口用于修改一个已存在的文件，或在 mode="create" 时创建新文件，并自动刷新相关语义与向量。

replace 和 append 要求文件已存在；create 仅用于创建新文件，目标路径已存在时返回 409 Conflict。目录始终会被拒绝。
create 只允许以下文本类扩展名：.md、.txt、.json、.yaml、.yml、.toml、.py、.js、.ts。父目录会自动创建。
不允许直接写入派生语义文件：.abstract.md、.overview.md、.relations.json。
文件内容会在 API 返回前完成更新；wait 只控制是否等待语义/向量刷新完成。
公共 API 已不再接受 regenerate_semantics 或 revectorize；写入后一定会自动刷新相关语义与向量。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口写入内容。

请求接口

URI	/api/v1/content/write	统一资源标识符
请求方法	POST	客户端请求类型
请求头	Content-Type: application/json	请求消息类型
	Authorization: Bearer	Bearer Token 鉴权

请求参数

参数	类型	必选	默认值	备注
uri	string	是	--	已存在文件的 URI `replace` 和 `append` 模式下文件必须已存在；`create` 模式下目标路径不能已存在。目录始终被拒绝。
content	string	是	--	要写入的新内容
mode	string	否	`replace`	写入模式：`replace`（替换）、`append`（追加）或 `create`（创建新文件）。`create` 只允许 `.md`、`.txt`、`.json`、`.yaml`、`.yml`、`.toml`、`.py`、`.js`、`.ts` 扩展名。
wait	bool	否	false	是否等待后台语义/向量刷新完成
timeout	float	否	null	当 `wait=true` 时的超时时间（秒）

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的数据对象
result.uri	写入文件的 Viking URI
result.root_uri	资源的根 URI
result.context_type	上下文类型
result.mode	写入模式
result.written_bytes	写入字节数
result.content_updated	内容是否已更新
result.semantic_status	语义刷新状态
result.vector_status	向量刷新状态
result.queue_status	队列处理状态（含 Semantic 和 Embedding 子项，每个子项包含 `processed`、`requeue_count`、`error_count`、`errors`）
error	失败时返回的错误对象
error.code	错误码字符串，常见值见下表
error.message	可读的错误描述

常见错误码：

error.code	HTTP 状态码	说明
UNAUTHENTICATED	401	缺少或无效的 API Key
INVALID_ARGUMENT	400	无效参数，如 uri 为目录、`create` 模式下扩展名不在允许列表中
INVALID_URI	400	无效的 Viking URI 格式
CONFLICT	409	`create` 模式下目标路径已存在
NOT_FOUND	404	`replace` 或 `append` 模式下文件不存在

完整示例

示例一：替换已有文件内容

curl -X POST "https://xxx/api/v1/content/write" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "uri": "viking://resources/docs/api.md",
    "content": "# Updated API\n\nFresh content.",
    "mode": "replace",
    "wait": true
  }'

执行成功返回：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "result": {
        "uri": "viking://resources/docs/api.md",
        "root_uri": "viking://resources/docs",
        "context_type": "resource",
        "mode": "replace",
        "written_bytes": 29,
        "content_updated": true,
        "semantic_status": "complete",
        "vector_status": "complete",
        "queue_status": {
            "Semantic": {
                "processed": 1,
                "requeue_count": 0,
                "error_count": 0,
                "errors": []
            },
            "Embedding": {
                "processed": 0,
                "requeue_count": 0,
                "error_count": 0,
                "errors": []
            }
        }
    }
}

最近更新时间：2026.05.26 11:19:27

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

示例一：替换已有文件内容 #

示例一：替换已有文件内容