本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Cohere Embed v3
<a name="model-parameters-embed-v3"></a>

**Topics**
+ [請求與回應](#model-parameters-embed-v3-request-response)
+ [程式碼範例](#api-inference-examples-cohere-embed-v3)

## 請求與回應
<a name="model-parameters-embed-v3-request-response"></a>

------
#### [ Request ]

這些 Cohere Embed 模型具有下列推論參數。

```
{
    "input_type": "search_document|search_query|classification|clustering|image",
    "texts":[string],
    "images":[image_base64_image_uri]
    "truncate": "NONE|START|END",
    "embedding_types": embedding_types
}
```

以下是必要的參數。
+ **texts** –要嵌入的模型字串陣列。為獲得最佳效能，我們建議將每個文字的長度減少到 512 個記號以下。1 個記號約為 4 個字元。

  以下是每個呼叫的文字和字元限制。

**每個呼叫的文字**  
    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/model-parameters-embed-v3.html)

**字元**  
    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/model-parameters-embed-v3.html)
+ **input\_type** – 在每個類型前面加上特殊字符，以區分彼此。除了混合類型以進行搜尋和檢索外，不應將不同類型混合在一起。在這種情況下，將您的主體嵌入到類型 `search_document`，並將查詢內嵌到類型 `search_query`。
  + `search_document` - 在搜尋使用案例中，當您為儲存在向量資料庫中的內嵌項目文件編碼時，可使用 `search_document`。
  + `search_query` - 查詢向量資料庫以尋找相關文件時使用 `search_query`。
  + `classification` - 使用內嵌項目作為文字分類器的輸入內容時使用 `classification`。
  + `clustering` - 使用 `clustering` 叢集內嵌項目。
  + `images` – 這是影像陣列。
    + 模型要嵌入的影像資料 URI 陣列。每次呼叫的影像數量上限為 1 (即模型僅支援一個影像輸入)。
    + 影像必須是有效的資料 URI。影像必須是 image/jpeg 或 image/png 格式，大小上限為 5MB。
    + 只能提供 “images” 或 “texts” 其中之一。

以下是選用參數：
+  **truncate** – 指定 API 如何處理超過字符長度上限的輸入。請使用下列其中一個：
  + `NONE` - (預設) 當輸入超過輸入記號長度上限時傳回錯誤。
  + `START` - 捨棄輸入開端。
  + `END` - 捨棄輸入的結尾。

  如果您指定 `START` 或 `END`，則模型會捨棄輸入，直到剩餘的輸入完全符合模型的輸入記號長度上限。
+  **embedding\_types** – 指定您要傳回的嵌入類型。選用且預設為 `None`，這會傳回 `Embed Floats` 回應類型。可以是下列一或多個類型：
  + `float` – 使用此值可傳回預設浮點數嵌入。
  + `int8` – 使用此值可傳回帶正負號的 int8 嵌入。
  + `uint8` – 使用此值可傳回不帶正負號的 int8 嵌入。
  + `binary` – 使用此值可傳回帶正負號的二進位嵌入。
  + `ubinary` – 使用此值可傳回不帶正負號的二進位嵌入。

如需詳細資訊，請參閱 Cohere 文件中的 [https://docs.cohere.com/reference/embed](https://docs.cohere.com/reference/embed)。

------
#### [ Response ]

來自對 `InvokeModel` 的呼叫的 `body` 回應如下：

```
{
    "embeddings": [
        [ {{array of 1024 floats.}} ]
    ],
    "id": string,
    "response_type" : "embeddings_floats,
    "texts": [string],
    "images": [image_description]
}
```

`body` 回應具有以下欄位：
+ **id** – 回應的識別符。
+ **response\_type** – 回應類型。這個值一律為 `embeddings_floats`。
+ **內嵌項目** - 內嵌項目陣列，其中每個內嵌項目都是具有 1024 個元素的浮點數陣列。`embeddings` 陣列的長度與原始 `texts` 陣列的長度相同。
+ **text** — 包含針對其傳回內嵌項目的文字項目的陣列。
+ **images** – 每個影像輸入的描述陣列。

  `image_description`image\_description 的格式如下：

  ```
  {
      "width": long,
      "height": long,
      "format": string,
      "bit_depth": long
  }
  ```

  如果使用影像做為輸入，則 `“texts”` 回應欄位將為空白陣列。反之亦然 (即使用文字時，`“images”` 不會出現在回應中)

如需詳細資訊，請參閱 [https://docs.cohere.com/reference/embed](https://docs.cohere.com/reference/embed)。

------

## 程式碼範例
<a name="api-inference-examples-cohere-embed-v3"></a>

這個範例展示如何呼叫 *Cohere Embed English* 模型。

```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to generate text embeddings using the Cohere Embed English model.
"""
import json
import logging
import boto3


from botocore.exceptions import ClientError

logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)


def generate_text_embeddings(model_id, body, region_name):
    """
    Generate text embedding by using the Cohere Embed model.
    Args:
        model_id (str): The model ID to use.
        body (str) : The reqest body to use.
        region_name (str): The AWS region to invoke the model on
    Returns:
        dict: The response from the model.
    """

    logger.info("Generating text embeddings with the Cohere Embed model %s", model_id)

    accept = '*/*'
    content_type = 'application/json'

    bedrock = boto3.client(service_name='bedrock-runtime', region_name=region_name)

    response = bedrock.invoke_model(
        body=body,
        modelId=model_id,
        accept=accept,
        contentType=content_type
    )

    logger.info("Successfully generated embeddings with Cohere model %s", model_id)

    return response


def main():
    """
    Entrypoint for Cohere Embed example.
    """

    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
    
    region_name = 'us-east-1'

    model_id = 'cohere.embed-english-v3'
    text1 = "hello world"
    text2 = "this is a test"
    input_type = "search_document"
    embedding_types = ["int8", "float"]

    try:
        body = json.dumps({
            "texts": [
                text1,
                text2],
            "input_type": input_type,
            "embedding_types": embedding_types
        })
        
        response = generate_text_embeddings(model_id=model_id, body=body, region_name=region_name)

        response_body = json.loads(response.get('body').read())

        print(f"ID: {response_body.get('id')}")
        print(f"Response type: {response_body.get('response_type')}")

        print("Embeddings")
        embeddings = response_body.get('embeddings')
        for i, embedding_type in enumerate(embeddings):
            print(f"\t{embedding_type} Embeddings:")
            print(f"\t{embeddings[embedding_type]}")

        print("Texts")
        for i, text in enumerate(response_body.get('texts')):
            print(f"\tText {i}: {text}")

    except ClientError as err:
        message = err.response["Error"]["Message"]
        logger.error("A client error occurred: %s", message)
        print("A client error occured: " +
              format(message))
    else:
        print(
            f"Finished generating text embeddings with Cohere model {model_id}.")


if __name__ == "__main__":
    main()
```

**輸入影像**

```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to generate image embeddings using the Cohere Embed English model.
"""
import json
import logging
import boto3
import base64


from botocore.exceptions import ClientError

logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)

def get_base64_image_uri(image_file_path: str, image_mime_type: str):
    with open(image_file_path, "rb") as image_file:
        image_bytes = image_file.read()
        base64_image = base64.b64encode(image_bytes).decode("utf-8")
    return f"data:{image_mime_type};base64,{base64_image}"


def generate_image_embeddings(model_id, body, region_name):
    """
    Generate image embedding by using the Cohere Embed model.
    Args:
        model_id (str): The model ID to use.
        body (str) : The reqest body to use.
        region_name (str): The AWS region to invoke the model on
    Returns:
        dict: The response from the model.
    """

    logger.info("Generating image embeddings with the Cohere Embed model %s", model_id)

    accept = '*/*'
    content_type = 'application/json'

    bedrock = boto3.client(service_name='bedrock-runtime', region_name=region_name)

    response = bedrock.invoke_model(
        body=body,
        modelId=model_id,
        accept=accept,
        contentType=content_type
    )

    logger.info("Successfully generated embeddings with Cohere model %s", model_id)

    return response


def main():
    """
    Entrypoint for Cohere Embed example.
    """

    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
    
    region_name = 'us-east-1'

    image_file_path = "image.jpg"
    image_mime_type = "image/jpg"

    model_id = 'cohere.embed-english-v3'
    input_type = "image"
    images = [get_base64_image_uri(image_file_path, image_mime_type)]
    embedding_types = ["int8", "float"]

    try:
        body = json.dumps({
            "images": images,
            "input_type": input_type,
            "embedding_types": embedding_types
        })
        
        response = generate_image_embeddings(model_id=model_id, body=body, region_name=region_name)

        response_body = json.loads(response.get('body').read())

        print(f"ID: {response_body.get('id')}")
        print(f"Response type: {response_body.get('response_type')}")

        print("Embeddings")
        embeddings = response_body.get('embeddings')
        for i, embedding_type in enumerate(embeddings):
            print(f"\t{embedding_type} Embeddings:")
            print(f"\t{embeddings[embedding_type]}")

        print("Texts")
        for i, text in enumerate(response_body.get('texts')):
            print(f"\tText {i}: {text}")

    except ClientError as err:
        message = err.response["Error"]["Message"]
        logger.error("A client error occurred: %s", message)
        print("A client error occured: " +
              format(message))
    else:
        print(
            f"Finished generating text embeddings with Cohere model {model_id}.")


if __name__ == "__main__":
    main()
```