Skip to content

migration.md

Latest commit

 

History

History
158 lines (120 loc) · 6.13 KB

migration.md

File metadata and controls

158 lines (120 loc) · 6.13 KB
Raw

Migrate from the legacy Python SDK

This guide covers the runtime clients imported from:

  • volcenginesdkarkruntime
  • byteplussdkarkruntime

Both migrate to the arkruntime distribution and Python package.

1. Migration order

Migrate one API flow at a time:

  1. Choose the target cloud: Volcengine (CN) or BytePlus.
  2. Install arkruntime, update imports, and select the regional sync or async client factory.
  3. Verify every request dictionary's discriminator, nesting, and field names.
  4. Update non-streaming Responses output traversal and streaming event types.
  5. Preserve response IDs, call IDs, and approval IDs across multi-turn flows.
  6. Add the required beta header to every built-in-tool request and remove any CN-only tool from a BytePlus target.
  7. Compile and smoke-test that flow before migrating the next one.

Do not apply a project-wide regular-expression replacement to request bodies or stream handlers. Their correct mapping depends on runtime structure and intent.

2. Dependency, import, and client mapping

Install the new package:

pip install arkruntime
Legacy New
from volcenginesdkarkruntime import Ark from arkruntime import Ark
from byteplussdkarkruntime import Ark from arkruntime import Ark
legacy .types... import root arkruntime.types...
Ark(...) CN: Ark.volc(...); BP: Ark.byteplus(...)
AsyncArk(...) CN: AsyncArk.volc(...); BP: AsyncArk.byteplus(...)

Remove volcengine-python-sdk or byteplus-python-sdk-v2 from application dependencies only after verifying no other imports need that distribution. arkruntime itself may install a Volcengine dependency for its authentication implementation; that is not a reason to keep legacy runtime imports.

If legacy code sets base_url, inspect it manually. Prefer the regional factory default. Retain a custom URL only when the deployment explicitly requires one.

3. Request-body mapping

Most keyword-based calls remain recognizable, but migration must validate the body as a discriminated union rather than assuming every old dictionary is accepted.

Intent New body
simple Responses prompt input="..."
message input input=[{"role": "user", "content": ...}]
text content part {"type": "input_text", "text": "..."}
image content part {"type": "input_image", "image_url": "..."}
function result {"type": "function_call_output", "call_id": id, "output": value}
MCP approval {"type": "mcp_approval_response", "approval_request_id": id, "approve": True}

Preserve previous_response_id when continuing a stored response. Preserve the same tool declarations in the follow-up request when required by the flow. Never collapse a content-part list into a string if it also contains media.

If an application creates request dictionaries dynamically, add fixture tests for the final kwargs passed to responses.create or chat.completions.create.

4. Output and stream mapping

Non-streaming Responses output must be traversed:

for item in response.output or []:
    if item.type == "message":
        for content in item.content:
            if content.type == "output_text":
                print(content.text)

There is no response.output_text convenience property in this SDK.

Chat stream text remains on chunk.choices[0].delta.content. Responses streams are typed unions. Import event types from arkruntime.types.responses and use isinstance:

if isinstance(event, ResponseTextDeltaEvent):
    consume(event.delta)
elif isinstance(event, ResponseCompletedEvent):
    response_id = event.response.id

Common legacy type mappings are:

Legacy New public type
ResponseFunctionToolCall ItemFunctionToolCall
McpApprovalRequest ItemFunctionMcpApprovalRequest
deep per-file event imports imports from arkruntime.types.responses

For a function call, capture call_id from a ResponseOutputItemDoneEvent whose item is ItemFunctionToolCall. For MCP, capture the approval request item and the completed response ID. Async code uses await plus async for; do not mechanically change it to the sync iteration pattern.

5. Extra headers and regional behavior

Headers are per-call keyword arguments:

client.responses.create(
    ...,
    extra_headers={"ark-beta-mcp": "true"},
)

MCP (ark-beta-mcp) works in CN and BytePlus. Web search (ark-beta-web-search), knowledge search (ark-beta-knowledge-search), Doubao App (ark-beta-doubao-app), and image process (ark-beta-image-process) are CN-only. Remove these tools from a BytePlus migration rather than silently dropping their headers or changing their request bodies.

6. Regional model IDs

Model names and endpoint IDs are cloud-specific. Prefer application configuration, and update any legacy hard-coded default when changing clouds:

API Volcengine (CN) example BytePlus example
Responses / Chat doubao-seed-2-1-pro-260628 seed-2-0-lite-260428
Multimodal / sparse embeddings doubao-embedding-vision-251215 skylark-embedding-vision-251215
Image generation doubao-seedream-5-0-pro-260628 dola-seedream-5-0-pro-260628
Video generation doubao-seedance-2-0-fast-260128 dreamina-seedance-2-0-fast-260128

Use a model or endpoint ID provisioned for the target account if it differs from these example defaults.

7. Validate the migration

  1. Search for legacy runtime imports and direct Ark(...) / AsyncArk(...) construction; none should remain in migrated Ark Runtime code.
  2. Run the project's formatter, type checker, and tests.
  3. Run python -m compileall over migrated source.
  4. Run one non-streaming request and verify output traversal.
  5. Run sync or async streaming through a completed event and verify error paths.
  6. Smoke-test each built-in tool with its beta header.
  7. Validate CN and BytePlus separately when supporting both. Do not reuse a key, model, endpoint ID, or client between regions.

Compilation alone does not prove a migration is correct: dictionary bodies, event dispatch, output traversal, regional model names, and headers are runtime contracts.