跳至主要內容

Bedrock 嵌入

支援的嵌入模型​

提供者LiteLLM 路由AWS 文件成本追蹤
Amazon Titanbedrock/amazon.titan-*Amazon Titan Embeddings✅
Amazon Novabedrock/amazon.nova-*Amazon Nova Embeddings✅
Coherebedrock/cohere.*Cohere Embeddings✅
TwelveLabsbedrock/twelvelabs.*, bedrock/us.twelvelabs.*, bedrock/eu.twelvelabs.*TwelveLabs, Marengo Embed 3.0✅

非同步 Invoke 支援​

LiteLLM 支援 AWS Bedrock 的 async-invoke 功能，適用於需要非同步處理的嵌入模型，特別適合大型媒體檔案（影片、音訊），或當您需要在背景處理嵌入時使用。

支援的模型​

提供者非同步呼叫路由使用情境
Amazon Novabedrock/async_invoke/amazon.nova-2-multimodal-embeddings-v1:0具分段功能的多模態嵌入，適用於長文本、影片和音訊
TwelveLabs Marengo Embed 2.7bedrock/async_invoke/twelvelabs.marengo-embed-2-7-v1:0影片、音訊、圖片和文本嵌入
TwelveLabs Marengo Embed 3.0bedrock/async_invoke/twelvelabs.marengo-embed-3-0-v1:0影片和音訊嵌入（文本和圖片同步執行，請參閱 Marengo Embed 3.0）

必要參數​

Bedrock 的 async invoke 只接受 base model ids，因此請在此使用 twelvelabs.marengo-embed-2-7-v1:0 或 twelvelabs.marengo-embed-3-0-v1:0，而不是 us. 或 eu. inference profile，否則 Bedrock 會以 The provided model doesn't support async inference 拒絕

使用 async-invoke 時，您必須提供：

參數說明必填
output_s3_uri儲存嵌入結果的 S3 URI✅ 是
input_type輸入類型："text"、"image"、"video" 或 "audio"（Marengo Embed 3.0 也支援 "text_image" 和 "multi_input"）✅ 是
aws_region_name此請求的 AWS 區域✅ 是

使用方式​

基本非同步 Invoke​

from litellm import embedding

# Text embedding with async-invoke
response = embedding(
    model="bedrock/async_invoke/twelvelabs.marengo-embed-2-7-v1:0",
    input=["Hello world from LiteLLM async invoke!"],
    aws_region_name="us-east-1",
    input_type="text",
    output_s3_uri="s3://your-bucket/async-invoke-output/"
)

print(f"Job submitted! Invocation ARN: {response._hidden_params._invocation_arn}")

影片/音訊嵌入​

# Video embedding (requires async-invoke)
response = embedding(
    model="bedrock/async_invoke/twelvelabs.marengo-embed-2-7-v1:0",
    input=["s3://your-bucket/video.mp4"],  # S3 URL for video
    aws_region_name="us-east-1",
    input_type="video",
    output_s3_uri="s3://your-bucket/async-invoke-output/"
)

print(f"Video embedding job submitted! ARN: {response._hidden_params._invocation_arn}")

以 Base64 進行圖片嵌入​

import base64

# Load and encode image
with open("image.jpg", "rb") as img_file:
    img_data = base64.b64encode(img_file.read()).decode('utf-8')
    img_base64 = f"data:image/jpeg;base64,{img_data}"

response = embedding(
    model="bedrock/async_invoke/twelvelabs.marengo-embed-2-7-v1:0",
    input=[img_base64],
    aws_region_name="us-east-1",
    input_type="image",
    output_s3_uri="s3://your-bucket/async-invoke-output/"
)

取得工作資訊​

取得 Job ID 與 Invocation ARN​

async-invoke 回應會在隱藏參數中包含 invocation ARN：

response = embedding(
    model="bedrock/async_invoke/twelvelabs.marengo-embed-2-7-v1:0",
    input=["Hello world"],
    aws_region_name="us-east-1",
    input_type="text",
    output_s3_uri="s3://your-bucket/async-invoke-output/"
)

# Access invocation ARN
invocation_arn = response._hidden_params._invocation_arn
print(f"Invocation ARN: {invocation_arn}")

# Extract job ID from ARN (last part after the last slash)
job_id = invocation_arn.split("/")[-1]
print(f"Job ID: {job_id}")

檢查工作狀態​

使用 LiteLLM 的 retrieve_batch 函式來檢查您的工作是否仍在處理中：

from litellm import retrieve_batch

def check_async_job_status(invocation_arn, aws_region_name="us-east-1"):
    """Check the status of an async invoke job using LiteLLM batch API"""
    try:
        response = retrieve_batch(
            batch_id=invocation_arn,  # Pass the invocation ARN here
            custom_llm_provider="bedrock",
            aws_region_name=aws_region_name
        )
        return response
    except Exception as e:
        print(f"Error checking job status: {e}")
        return None

# Check status
status = check_async_job_status(invocation_arn, "us-east-1")
if status:
    print(f"Job Status: {status.status}")  # "in_progress", "completed", or "failed"
    print(f"Output Location: {status.metadata['output_file_id']}")  # S3 URI where results are stored

透過輪詢直到完成​

以下是一個完整的工作完成輪詢範例：

def wait_for_async_job(invocation_arn, aws_region_name="us-east-1", max_wait=3600):
    """Poll job status until completion"""
    start_time = time.time()
    
    while True:
        status = retrieve_batch(
            batch_id=invocation_arn,
            custom_llm_provider="bedrock",
            aws_region_name=aws_region_name,
        )
        
        if status.status == "completed":
            print("✅ Job completed!")
            return status
        elif status.status == "failed":
            error_msg = status.metadata.get('failure_message', 'Unknown error')
            raise Exception(f"❌ Job failed: {error_msg}")
        else:
            elapsed = time.time() - start_time
            if elapsed > max_wait:
                raise TimeoutError(f"Job timed out after {max_wait} seconds")
            
            print(f"⏳ Job still processing... (elapsed: {elapsed:.0f}s)")
            time.sleep(10)  # Wait 10 seconds before checking again

# Wait for completion
completed_status = wait_for_async_job(invocation_arn)
output_s3_uri = completed_status.metadata['output_file_id']
print(f"Results available at: {output_s3_uri}")

注意： 實際的嵌入結果會儲存在 S3 中。工作完成後，請從 status.metadata['output_file_id'] 中指定的 S3 位置下載結果。結果將採用 JSON/JSONL 格式，並包含嵌入向量。

TwelveLabs Marengo Embed 3.0​

Marengo Embed 3.0（twelvelabs.marengo-embed-3-0-v1:0，並為 us-east-1 和 eu-west-1 提供 us. 與 eu. inference profiles）會回傳 512 維向量，且可處理最多 500 個 tokens 的文本。文本、圖片、文本加圖片，以及多圖片輸入會透過 bedrock/<model id> 同步執行；影片和音訊則透過 bedrock/async_invoke/twelvelabs.marengo-embed-3-0-v1:0 搭配 output_s3_uri，並使用 base model id，因為 Bedrock 的 async invoke 會拒絕 inference profiles。3.0 傳送給 Bedrock 的 request body 與 2.7 不同，而 LiteLLM 會從相同的 input_type 參數建立它，因此從 2.7（預定於 2026-11-30 淘汰）切換時，變更的是 model id

輸入類型​

input_typeinput額外參數
text（預設）要嵌入的文本
imagebase64 圖片或 s3:// uri
text_image文本media_source：base64 圖片或 s3:// uri
multi_input文本，並將每張圖片參照為 <@name>media_sources：名稱到 base64 圖片或 s3:// uri 的對應
video、audios3:// uri 或 base64 媒體，僅限非同步呼叫startSec、endSec、segmentation、embeddingOption、embeddingType、embeddingScope，如 AWS 所記載

inferenceId 和 bucketOwner（適用於由其他帳戶擁有的 s3:// uri）會在每種輸入類型上傳遞。未提供 text_image 的 media_source 請求，或未提供 multi_input 的 media_sources 請求，會因缺少的參數名稱而遭到 400 拒絕。Marengo 2.7 的 textTruncate、lengthSec、useFixedLengthSec 和 minClipSec，以及任何其他輸入類型上的影片與音訊選項，在 3.0 上若未設定 drop_params，都會以 400 拒絕，否則會直接略過

Proxy 設定​

model_list:
  - model_name: marengo-3
    litellm_params:
      model: bedrock/us.twelvelabs.marengo-embed-3-0-v1:0
      aws_region_name: us-east-1
  - model_name: marengo-3-async
    litellm_params:
      model: bedrock/async_invoke/twelvelabs.marengo-embed-3-0-v1:0
      aws_region_name: us-east-1

文本​

curl http://0.0.0.0:4000/v1/embeddings \
  -H "Authorization: Bearer $LITELLM_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "marengo-3", "input": "a dog running on the beach", "input_type": "text"}'

圖片​

curl http://0.0.0.0:4000/v1/embeddings \
  -H "Authorization: Bearer $LITELLM_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "marengo-3", "input": "<base64 image>", "input_type": "image"}'

文本加圖片​

curl http://0.0.0.0:4000/v1/embeddings \
  -H "Authorization: Bearer $LITELLM_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "marengo-3", "input": "a duck", "input_type": "text_image", "media_source": "s3://your-bucket/duck.png"}'

多張圖片​

curl http://0.0.0.0:4000/v1/embeddings \
  -H "Authorization: Bearer $LITELLM_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "marengo-3", "input": "a photo of <@bird> on water", "input_type": "multi_input", "media_sources": {"bird": "<base64 image>"}}'

透過 async invoke 的影片​

from litellm import embedding

response = embedding(
    model="bedrock/async_invoke/twelvelabs.marengo-embed-3-0-v1:0",
    input=["s3://your-bucket/video.mp4"],
    aws_region_name="us-east-1",
    input_type="video",
    embeddingOption=["visual", "audio"],
    segmentation={"method": "fixed", "fixed": {"durationSec": 10}},
    output_s3_uri="s3://your-bucket/async-invoke-output/",
)
print(response._hidden_params._invocation_arn)

Amazon Nova 多模態嵌入​

Amazon Nova 支援文字、圖片、影片與音訊的多模態嵌入。它提供彈性的嵌入維度與用途，針對不同使用情境最佳化。

支援的功能​

  • 模態：文字、圖片、影片、音訊
  • 維度：256、384、1024、3072（預設：3072）
  • 嵌入用途：
    • GENERIC_INDEX（預設）
    • GENERIC_RETRIEVAL
    • TEXT_RETRIEVAL
    • IMAGE_RETRIEVAL
    • VIDEO_RETRIEVAL
    • AUDIO_RETRIEVAL
    • CLASSIFICATION
    • CLUSTERING

文字嵌入​

from litellm import embedding

response = embedding(
    model="bedrock/amazon.nova-2-multimodal-embeddings-v1:0",
    input=["Hello, world!"],
    aws_region_name="us-east-1",
    dimensions=1024,  # Optional: 256, 384, 1024, or 3072
)

print(response.data[0].embedding)

以 Base64 進行圖片嵌入​

Amazon Nova 可使用標準 data URL 格式接受 base64 格式的圖片：

import base64
from litellm import embedding

# Method 1: Load image from file
with open("image.jpg", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode('utf-8')
    # Create data URL with proper format
    image_base64 = f"data:image/jpeg;base64,{image_data}"

response = embedding(
    model="bedrock/amazon.nova-2-multimodal-embeddings-v1:0",
    input=[image_base64],
    aws_region_name="us-east-1",
    dimensions=1024,
)

print(f"Image embedding: {response.data[0].embedding[:10]}...")  # First 10 dimensions

支援的圖片格式​

Nova 支援以下圖片格式：

  • JPEG: data:image/jpeg;base64,...
  • PNG: data:image/png;base64,...
  • GIF: data:image/gif;base64,...
  • WebP: data:image/webp;base64,...

含錯誤處理的完整範例​

import base64
from litellm import embedding

def get_image_embedding(image_path, dimensions=1024):
    """
    Get embedding for an image file.
    
    Args:
        image_path: Path to the image file
        dimensions: Embedding dimension (256, 384, 1024, or 3072)
    
    Returns:
        List of embedding values
    """
    try:
        # Determine image format from file extension
        if image_path.lower().endswith('.png'):
            mime_type = "image/png"
        elif image_path.lower().endswith(('.jpg', '.jpeg')):
            mime_type = "image/jpeg"
        elif image_path.lower().endswith('.gif'):
            mime_type = "image/gif"
        elif image_path.lower().endswith('.webp'):
            mime_type = "image/webp"
        else:
            raise ValueError(f"Unsupported image format: {image_path}")
        
        # Read and encode image
        with open(image_path, "rb") as image_file:
            image_data = base64.b64encode(image_file.read()).decode('utf-8')
            image_base64 = f"data:{mime_type};base64,{image_data}"
        
        # Get embedding
        response = embedding(
            model="bedrock/amazon.nova-2-multimodal-embeddings-v1:0",
            input=[image_base64],
            aws_region_name="us-east-1",
            dimensions=dimensions,
        )
        
        return response.data[0].embedding
        
    except Exception as e:
        print(f"Error getting image embedding: {e}")
        raise

# Example usage
image_embedding = get_image_embedding("photo.jpg", dimensions=1024)
print(f"Got embedding with {len(image_embedding)} dimensions")

錯誤處理​

常見錯誤​

錯誤原因解決方案
ValueError: output_s3_uri cannot be empty缺少 S3 輸出 URI提供有效的 S3 URI
ValueError: Input type 'video' requires async_invoke route在未使用 async-invoke 的情況下使用影片/音訊使用 bedrock/async_invoke/ 模型前綴
ValueError: input_type is required缺少輸入類型參數指定 input_type 參數

錯誤處理範例​

try:
    response = embedding(
        model="bedrock/async_invoke/twelvelabs.marengo-embed-2-7-v1:0",
        input=["Hello world"],
        aws_region_name="us-east-1",
        input_type="text",
        output_s3_uri="s3://your-bucket/output/"  # Required for async-invoke
    )
    print("Job submitted successfully!")
    
except ValueError as e:
    if "output_s3_uri cannot be empty" in str(e):
        print("Error: Please provide a valid S3 output URI")
    elif "requires async_invoke route" in str(e):
        print("Error: Use async_invoke model for video/audio inputs")
    else:
        print(f"Error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

最佳做法​

  1. 大型檔案使用 async-invoke：影片與音訊檔案更適合以非同步方式處理
  2. 使用 LiteLLM batch API：狀態檢查請使用 retrieve_batch()，而非直接呼叫 Bedrock API
  3. 監控工作狀態：定期使用 batch API 檢查工作狀態，以知道結果何時就緒
  4. 妥善處理錯誤：針對網路問題與工作失敗實作正確的錯誤處理
  5. 設定適當的逾時時間：考量大型檔案的處理時間
  6. 大型輸入使用 S3：對於影片/音訊，請使用 S3 URL，而非 base64 編碼

限制​

  • TwelveLabs Marengo 與 Amazon Nova 模型支援 async-invoke
  • 結果會儲存在 S3，且必須使用輸出檔案 ID 另外擷取
  • 工作狀態檢查需要使用 LiteLLM 的 retrieve_batch() 函式
  • LiteLLM 沒有內建輪詢機制（必須自行實作狀態檢查迴圈）

API 金鑰​

這可以設定為環境變數，或作為 params to litellm.embedding() 傳入

import os
os.environ["AWS_ACCESS_KEY_ID"] = ""        # Access key
os.environ["AWS_SECRET_ACCESS_KEY"] = ""    # Secret access key
os.environ["AWS_REGION_NAME"] = ""           # us-east-1, us-east-2, us-west-1, us-west-2

使用方式​

LiteLLM Python SDK​

from litellm import embedding
response = embedding(
    model="bedrock/amazon.titan-embed-text-v1",
    input=["good morning from litellm"],
)
print(response)

LiteLLM Proxy Server​

1. 設定 config.yaml​

model_list:
  - model_name: titan-embed-v1
    litellm_params:
      model: bedrock/amazon.titan-embed-text-v1
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-east-1
  - model_name: titan-embed-v2
    litellm_params:
      model: bedrock/amazon.titan-embed-text-v2:0
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-east-1

2. 啟動 Proxy​

litellm --config /path/to/config.yaml

3. 與 OpenAI Python SDK 搭配使用​

import openai
client = openai.OpenAI(
    api_key="anything",
    base_url="http://0.0.0.0:4000"
)

response = client.embeddings.create(
    input=["good morning from litellm"],
    model="titan-embed-v1"
)
print(response)

4. 與 LiteLLM Python SDK 搭配使用​

import litellm
response = litellm.embedding(
    model="titan-embed-v1", # model alias from config.yaml
    input=["good morning from litellm"],
    api_base="http://0.0.0.0:4000",
    api_key="anything"
)
print(response)

支援的 AWS Bedrock 嵌入模型​

模型名稱用途支援的額外 OpenAI 參數
Amazon Nova Multimodal Embeddingsembedding(model="bedrock/amazon.nova-2-multimodal-embeddings-v1:0", input=input)支援多模態輸入（文本、圖片、影片、音訊）、多種用途、維度（256、384、1024、3072）
Titan Embeddings V2embedding(model="bedrock/amazon.titan-embed-text-v2:0", input=input)這裡
Titan Embeddings - V1embedding(model="bedrock/amazon.titan-embed-text-v1", input=input)這裡
Titan Multimodal Embeddingsembedding(model="bedrock/amazon.titan-embed-image-v1", input=input)這裡
TwelveLabs Marengo Embed 2.7embedding(model="bedrock/us.twelvelabs.marengo-embed-2-7-v1:0", input=input)支援多模態輸入（文本、影片、音訊、圖片）
TwelveLabs Marengo Embed 3.0embedding(model="bedrock/us.twelvelabs.marengo-embed-3-0-v1:0", input=input)文本、圖片、text_image 和 multi_input 同步執行，影片和音訊透過 async invoke，512 維度
Cohere Embeddings - Englishembedding(model="bedrock/cohere.embed-english-v3", input=input)這裡
Cohere Embeddings - Multilingualembedding(model="bedrock/cohere.embed-multilingual-v3", input=input)這裡
Cohere Embed v4embedding(model="bedrock/cohere.embed-v4:0", input=input)支援文本和圖片輸入，可設定維度（256、512、1024、1536），128k context 長度

進階 - 捨棄不支援的參數​

進階 - 傳遞模型/提供者專屬參數​

LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →