后端¶

Backend 描述一个可供 Workspace 使用的模型服务；Endpoint 描述该服务的具体地址。Backend ID 是二者的关联键，也是更新、探测和删除操作的入口。

返回对象¶

ProviderBackend 的公开字段包括：

字段	含义
`id`、`name`	Backend 标识和名称
`type`	服务端记录的 Provider / 协议类型
`reasoning_control_protocol`	推理控制协议；是否适用取决于 Backend 类型
`timeout_seconds`	调用超时，单位为秒
`models`	Backend 配置的模型名
`supported_mime_types`	Parser Backend 支持的 MIME 类型
`endpoints`	随 Backend 返回的 Endpoint 列表
`created_at`、`updated_at`	服务端时间值

ProviderEndpoint 包含 id、backend_id、address、status、created_at 和 updated_at。API Key 不在 Backend 或 Endpoint 返回类型中；不要期待读取接口返回密钥。

创建与读取¶

Backend 的创建见提供方。创建结果中的 Handle 可以直接读取当前配置：

current = backend.info()
print(current.id, current.name, list(current.models))

endpoints = backend.endpoints()
for endpoint in endpoints.endpoints:
    print(endpoint.id, endpoint.address, endpoint.status)

current, err := backend.Info(ctx)
if err != nil {
    return err
}
fmt.Println(current.GetId(), current.GetName(), current.GetModels())

endpoints, err := backend.Endpoints(ctx)
if err != nil {
    return err
}
for _, endpoint := range endpoints.GetEndpoints() {
    fmt.Println(endpoint.GetId(), endpoint.GetAddress(), endpoint.GetStatus())
}

列表返回空集合时表示当前没有可见 Endpoint，不应据此猜测默认地址。

更新 Backend¶

更新接口采用独立的 Update 选项。只传需要变更的字段，避免把过期的读取结果整体写回。

updated = backend.update(
    sdk.with_provider_backend_update_name(new_name),
    sdk.with_provider_backend_update_timeout_seconds(90),
    sdk.with_provider_backend_update_models(*selected_models),
)

updated, err := backend.Update(
    ctx,
    sdk.WithProviderBackendUpdateName(newName),
    sdk.WithProviderBackendUpdateTimeoutSeconds(90),
    sdk.WithProviderBackendUpdateModels(selectedModels...),
)

SDK 还公开更新 API Key、推理控制协议和支持 MIME 类型的选项。调用前先确认它们适用于当前 Provider 类型。模型列表和 MIME 类型是列表值；传入空列表的服务端含义未由公开 SDK 固定，若要清空配置，应先以当前产品行为为准。

管理 Endpoint¶

新增 Endpoint 只要求一个非空地址：

created_endpoint = backend.create_endpoint(model_endpoint)
print(created_endpoint.id, created_endpoint.address)

createdEndpoint, err := backend.CreateEndpoint(ctx, modelEndpoint)
if err != nil {
    return err
}
fmt.Println(createdEndpoint.GetId(), createdEndpoint.GetAddress())

Endpoint 状态通过 Backend Handle 更新：

result = backend.set_endpoint_status(str(endpoint_id), endpoint_status)
if not result.success:
    raise RuntimeError("endpoint status was not updated")

result, err := backend.SetEndpointStatus(ctx, endpointID, endpointStatus)
if err != nil {
    return err
}
if !result.GetSuccess() {
    return errors.New("endpoint status was not updated")
}

公开 SDK 没有声明允许的状态枚举。endpoint_status 必须使用目标环境 API 或产品界面已经提供的值，不要自行假定 enabled、disabled 等字符串。更新后再次调用 endpoints() / Endpoints() 验证服务端状态。

当前 Handle 没有公开“更新 Endpoint 地址”或“删除单个 Endpoint”的便捷方法。不要用猜测的 HTTP 路由补齐；需要这类操作时，以当前产品界面或已发布 API 为准。

探测已配置 Backend¶

models = backend.probe_models(
    sdk.with_provider_backend_api_key(os.environ["MODEL_API_KEY"]),
)

models, err := backend.ProbeModels(
    ctx,
    sdk.WithProviderBackendAPIKey(os.Getenv("MODEL_API_KEY")),
)

LLM Backend 的探测要求 API Key；Embedding Backend 可以不传额外请求体；Parser Backend 不支持模型探测。探测结果是字符串模型列表，不会自动覆盖 Backend 的 models 配置。

删除 Backend¶

delete() / Delete() 删除整个 Backend，而不是一个 Endpoint。执行前应读取最新配置，并确认没有工作流、知识库或其他资源继续使用该 Backend。

deleted = backend.delete()
if not deleted.success:
    raise RuntimeError("backend was not deleted")

deleted, err := backend.Delete(ctx)
if err != nil {
    return err
}
if !deleted.GetSuccess() {
    return errors.New("backend was not deleted")
}

删除成功后重新列出该 Provider 的 Backends，确认目标 ID 已不可见。SDK 没有声明删除的级联范围或恢复机制，因此不要把删除当作可自动回滚操作。