本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Cohere Command R 和 Command R\+ 模型 您可以使用 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 或 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) (串流) 對 Cohere Command R 和 Cohere Command R\+ 模型進行推論呼叫。您需要您想要使用的模型的模型 ID。若要取得模型 ID，請參閱 [Amazon Bedrock 中支援的基礎模型](models-supported.md)。 **提示** 對於對話式應用程式，我們建議您使用 Converse API。Converse API 提供一組統一的參數，可用於支援訊息的所有模型。如需詳細資訊，請參閱[使用 Converse API 進行推論](conversation-inference.md)。 **Topics** + [請求與回應](#model-parameters-cohere-command-request-response) + [程式碼範例](#api-inference-examples-cohere-command-r) ## 請求與回應 ------ #### [ Request ] 這些 Cohere Command 模型具有下列推論參數。 ``` { "message": string, "chat_history": [ { "role":"{{USER or CHATBOT}}", "message": string } ], "documents": [ {"title": string, "snippet": string}, ], "search_queries_only" : boolean, "preamble" : string, "max_tokens": int, "temperature": float, "p": float, "k": float, "prompt_truncation" : string, "frequency_penalty" : float, "presence_penalty" : float, "seed" : int, "return_prompt" : boolean, "tools" : [ { "name": string, "description": string, "parameter_definitions": { "{{parameter name}}": { "description": string, "type": string, "required": boolean } } } ], "tool_results" : [ { "call": { "name": string, "parameters": { "{{parameter name}}": string } }, "outputs": [ { "{{text}}": string } ] } ], "stop_sequences": [string], "raw_prompting" : boolean } ``` 下列是必要的參數。 + **message** – (必要) 模型要回應的文字輸入。 以下是選用參數。 + **chat\_history** – 使用者與模型之間的先前訊息清單，旨在提供模型對話內容以回應使用者的訊息。 以下是必要欄位。 + `role` – 訊息的角色。有效值為 `USER` 或 `CHATBOT` 字符。 + `message` – 訊息的文字內容。 以下是 `chat_history` 欄位的範例 JSON。 ``` "chat_history": [ {"role": "USER", "message": "Who discovered gravity?"}, {"role": "CHATBOT", "message": "The man who is widely credited with discovering gravity is Sir Isaac Newton"} ] ``` + **documents** – 模型可以引用的文字清單，以產生更準確的回覆。每個文件都是字串-字串字典。產生的產生包含參考其中一些文件的引用。我們建議您將字典中字串的總字數保持在 300 個字以下。可以選擇性地提供 `_excludes` 欄位 (字串陣列)，以忽略向模型顯示的一些鍵值對。如需詳細資訊，請參閱 Cohere 文件中的《[文件模式指南](https://docs.cohere.com/docs/retrieval-augmented-generation-rag#document-mode)》。 以下是 `documents` 欄位的範例 JSON。 ``` "documents": [ {"title": "Tall penguins", "snippet": "Emperor penguins are the tallest."}, {"title": "Penguin habitats", "snippet": "Emperor penguins only live in Antarctica."} ] ``` + **search\_queries\_only** – 預設為 `false`。當 `true` 時，回應只會包含產生的搜尋查詢清單，但不會進行任何搜尋，也不會產生模型對使用者 `message` 的回覆。 + **preamble** – 覆寫搜尋查詢產生的預設前言。不會影響工具使用產生。 + **max\_tokens** – 模型應在回應中產生的字符數目上限。請注意，設定低值可能會導致產生不完整的產生。與 `tools` 或 `documents` 欄位搭配使用時，設定 `max_tokens` 可能會導致不完整或無產生。 + **temperature** — 使用較低的值來降低回應中的隨機性。增加 `p` 參數的值可進一步最大化隨機性。 [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/model-parameters-cohere-command-r-plus.html) + **p** – Top P。使用較低的值來忽略較不可能的選項。 [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/model-parameters-cohere-command-r-plus.html) + **k** – Top K。指定模型用來產生下一個字符的字符選擇數。 [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/model-parameters-cohere-command-r-plus.html) + **prompt\_truncation** – 預設為 `OFF`。說明提示的建構方式。將 `prompt_truncation` 設為 `AUTO_PRESERVE_ORDER` 時，將捨棄 `chat_history` 和 `documents` 中的某些元素，以建構符合模型內容長度限制的提示。在此程序中，文件和聊天歷史記錄的順序將會保留。將 `prompt_truncation`` 設為 `OFF` 時，不會捨棄任何元素。 + **frequency\_penalty** – 用於減少所產生字符的重複性。此值愈高，對先前存在的字符套用的處罰就愈重，且會與這些字符已出現在提示或先前世代中的次數成比例。 [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/model-parameters-cohere-command-r-plus.html) + **presence\_penalty** – 用於減少所產生字符的重複性。與 `frequency_penalty` 類似，但此懲罰會平均套用至已出現的所有字符，無論其確切頻率為何。 [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/model-parameters-cohere-command-r-plus.html) + **seed** – 如果指定，後端將盡最可能確定地取樣字符，因此具有相同種子和參數的重複請求應傳回相同的結果。不過，無法完全保證確定性。 + **return\_prompt** – 指定 `true` 以傳回已傳送至模型的完整提示。預設值為 `false`。在回應中，`prompt` 欄位中的提示。 + **tools** – 在產生文字回應之前，模型可能建議調用的可用工具 (函數) 清單。當傳遞 `tools` (不含 `tool_results`) 時，回應中的 `text` 欄位將是 `""`，而回應中的 `tool_calls` 欄位將填入需要進行的工具呼叫清單。如果不需要進行呼叫，則 `tool_calls` 陣列將為空白。 如需詳細資訊，請參閱 Cohere 文件中的[工具使用](https://docs.cohere.com/docs/tool-use)。 **提示** 我們建議您使用 Converse API 將工具使用整合至您的應用程式。如需詳細資訊，請參閱[使用工具完成 Amazon Bedrock 模型回應](tool-use.md)。 以下是 `tools` 欄位的範例 JSON。 ``` [ { "name": "top_song", "description": "Get the most popular song played on a radio station.", "parameter_definitions": { "sign": { "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP.", "type": "str", "required": true } } } ] ``` 如需詳細資訊，請參閱 Cohere 文件中的[單一步驟工具使用 (函數呼叫)](https://docs.cohere.com/docs/tool-use)。 + **tools\_results** – 上一個聊天回合中調用模型建議工具的結果清單。結果用於產生文字回應，並在引文中參考。使用 `tool_results` 時，`tools` 也必須傳遞。每個 `tool_result` 都包含如何調用的資訊，以及字典形式的輸出清單。Cohere 獨特的精細引用邏輯要求輸出為清單。如果輸出只是一個項目，例如 `{"status": 200}`，您仍然應該將它包裝在清單中。 如需詳細資訊，請參閱 Cohere 文件中的[工具使用](https://docs.cohere.com/docs/tool-use)。 以下是 `tools_results` 欄位的範例 JSON。 ``` [ { "call": { "name": "top_song", "parameters": { "sign": "WZPZ" } }, "outputs": [ { "song": "Elemental Hotel" } ] } ] ``` + **stop\_sequences** – 停止序列的清單。偵測到停止序列後，模型會停止產生進一步的字符。 + **raw\_prompting** – 指定 `true`，在不進行任何預先處理的情況下將使用者的 `message` 傳送至模型，否則為 false。 ------ #### [ Response ] 回應具有以下可能的欄位： ``` { "response_id": string, "text": string, "generation_id": string, "citations": [ { "start": int, "end": int, "text": "string", "document_ids": [ "string" ] } ], "finish_reason": string, "tool_calls": [ { "name": string, "parameters": { "{{parameter name}}": string } } ], { "meta": { "api_version": { "version": string }, "billed_units": { "input_tokens": int, "output_tokens": int } } } ``` + **response\_id** — 聊天完成的唯一識別符 + **text** — 模型對聊天訊息輸入的回應。 + **generation\_id** — 聊天完成的唯一識別符，與 Cohere 平台上的意見回饋端點搭配使用。 + **citations** — 產生的回覆的內嵌引文陣列和相關聯的中繼資料。包含下列欄位： + **start** — 引文開始的索引，從 0 開始。 + **end** — 引文結尾的索引，從 0 開始。 + **text** — 引文相關的文字。 + **document\_ids** — 對應至文字所引用文件的文件 ID 陣列。 + **prompt** — 已傳送至模型的完整提示。指定要傳回此欄位的 `return_prompt` 欄位。 + **finish\_reason** — 模型停止產生輸出的原因。可為下列任何一項： + **complete** — 完成已結束產生字符，確定這是獲得最佳效能的結束原因。 + **error\_toxic** — 由於我們的內容篩選條件，因此無法完成產生。 + **error\_limit** — 由於已達到模型的內容限制，因此無法完成產生。 + **error** — 由於發生錯誤，因此無法完成產生。 + **user\_cancel** — 無法完成產生，因為使用者已將其停止。 + **max\_tokens** — 無法完成產生，因為使用者在請求中指定了 `max_tokens` 限制，且已達到此限制。可能無法獲得最佳效能。 + **tool\_calls** – 呼叫的適當工具清單。只有在您指定 `tools` 輸入欄位時才傳回。 如需詳細資訊，請參閱 Cohere 文件中的[工具使用](https://docs.cohere.com/docs/tool-use)。 **提示** 我們建議您使用 Converse API 將工具使用整合至您的應用程式。如需詳細資訊，請參閱[使用工具完成 Amazon Bedrock 模型回應](tool-use.md)。 以下是 `tool_calls` 欄位的範例 JSON。 ``` [ { "name": "top_song", "parameters": { "sign": "WZPZ" } } ] ``` + **meta** — API 用量資料 (僅存在於串流中)。 + `api_version` — API 版本。版本位於 `version` 欄位中。 + `billed_units` — 計費單位。可能值為： + `input_tokens` — 已計費的輸入字符數目。 + `output_tokens` — 已計費的輸出字符數目。 ------ ## 程式碼範例 此範例展示如何呼叫 *Cohere Command R* 模型。 ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to use the Cohere Command R model. """ import json import logging import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def generate_text(model_id, body): """ Generate text using a Cohere Command R model. Args: model_id (str): The model ID to use. body (str) : The reqest body to use. Returns: dict: The response from the model. """ logger.info("Generating text with Cohere model %s", model_id) bedrock = boto3.client(service_name='bedrock-runtime') response = bedrock.invoke_model( body=body, modelId=model_id ) logger.info( "Successfully generated text with Cohere Command R model %s", model_id) return response def main(): """ Entrypoint for Cohere example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") model_id = 'cohere.command-r-v1:0' chat_history = [ {"role": "USER", "message": "What is an interesting new role in AI if I don't have an ML background?"}, {"role": "CHATBOT", "message": "You could explore being a prompt engineer!"} ] message = "What are some skills I should have?" try: body = json.dumps({ "message": message, "chat_history": chat_history, "max_tokens": 2000, "temperature": 0.6, "p": 0.5, "k": 250 }) response = generate_text(model_id=model_id, body=body) response_body = json.loads(response.get('body').read()) response_chat_history = response_body.get('chat_history') print('Chat history\n------------') for response_message in response_chat_history: if 'message' in response_message: print(f"Role: {response_message['role']}") print(f"Message: {response_message['message']}\n") print("Generated text\n--------------") print(f"Stop reason: {response_body['finish_reason']}") print(f"Response text: \n{response_body['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 with Cohere model {model_id}.") if __name__ == "__main__": main() ```