Merge pull request #4535 from hhunter-ms/issue_4522

[Conversation API] Add missing metadata fields
dapr · Feb 14, 2025 · 589ad1c · 589ad1c
2 parents 402d497 + 6357a5b
commit 589ad1c
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 8 deletions.
diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md
@@ -17,7 +17,7 @@ Dapr provides an API to interact with Large Language Models (LLMs) and enables c
 This endpoint lets you converse with LLMs.
 
 ```
-POST /v1.0-alpha1/conversation/<llm-name>/converse
+POST http://localhost:<daprPort>/v1.0-alpha1/conversation/<llm-name>/converse
 ```
 
 ### URL parameters
@@ -30,17 +30,40 @@ POST /v1.0-alpha1/conversation/<llm-name>/converse
 
 | Field | Description |
 | --------- | ----------- |
-| `conversationContext` |  |
-| `inputs` | |
-| `parameters` | | 
+| `conversationContext` | The ID of an existing chat room (like in ChatGPT). |
+| `inputs` | Inputs for the conversation. Multiple inputs at one time are supported. |
+| `metadata` | [Metadata](#metadata) passed to conversation components. |
 
+#### Metadata
+
+Metadata can be sent in the request’s URL. It must be prefixed with `metadata.`, as shown in the table below.
+
+| Parameter | Description |
+| --------- | ----------- |
+| `metadata.key` | The API key for the component. `key` is not applicable to the [AWS Bedrock component]({{< ref "aws-bedrock.md#authenticating-aws" >}}). |
+| `metadata.model` | The Large Language Model you're using. Value depends on which conversation component you're using. `model` is not applicable to the [DeepSeek component]({{< ref deepseek.md >}}). |
+| `metadata.cacheTTL` | A time-to-live value for a prompt cache to expire. Uses Golang duration format. |
+
+For example, to call for [Anthropic]({{< ref anthropic.md >}}):
+
+```bash
+curl POST http://localhost:3500/v1.0-alpha1/conversation/anthropic/converse?metadata.key=key1&metadata.model=claude-3-5-sonnet-20240620&metadata.cacheTTL=10m
+```
+
+{{% alert title="Note" color="primary" %}}
+The metadata parameters available depend on the conversation component you use. [See all the supported components for the conversation API.]({{< ref supported-conversation >}})
+{{% /alert %}}
 
 ### Request content
 
 ```json
 REQUEST = {
   "inputs": ["what is Dapr", "Why use Dapr"],
-  "parameters": {},
+  "metadata": {
+    "model": "model-type-based-on-component-used",
+    "key": "authKey",
+    "cacheTTL": "10m",
+  }
 }
 ```
 
@@ -50,7 +73,7 @@ Code | Description
 ---- | -----------
 `202`  | Accepted
 `400`  | Request was malformed
-`500`  | Request formatted correctly, error in dapr code or underlying component
+`500`  | Request formatted correctly, error in Dapr code or underlying component
 
 ### Response content
 
@@ -71,4 +94,5 @@ RESPONSE  = {
 
 ## Next steps
 
-[Conversation API overview]({{< ref conversation-overview.md >}})
+- [Conversation API overview]({{< ref conversation-overview.md >}})
+- [Supported conversation components]({{< ref supported-conversation >}})
diff --git a/...content/en/reference/components-reference/supported-conversation/aws-bedrock.md b/...content/en/reference/components-reference/supported-conversation/aws-bedrock.md
@@ -37,6 +37,10 @@ The above example uses secrets as plain strings. It is recommended to use a secr
 | `model` | N | The LLM to use. Defaults to Bedrock's default provider model from Amazon.  | `amazon.titan-text-express-v1` |
 | `cacheTTL` | N | A time-to-live value for a prompt cache to expire. Uses Golang duration format.  | `10m` |
 
+## Authenticating AWS
+
+Instead of using a `key` parameter, AWS Bedrock authenticates using Dapr's standard method of IAM or static credentials. [Learn more about authenticating with AWS.]({{< ref authenticating-aws.md >}})
+
 ## Related links
 
 - [Conversation API overview]({{< ref conversation-overview.md >}})
diff --git a/...cs/content/en/reference/components-reference/supported-conversation/deepseek.md b/...cs/content/en/reference/components-reference/supported-conversation/deepseek.md
@@ -32,7 +32,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr
 | Field              | Required | Details | Example |
 |--------------------|:--------:|---------|---------|
 | `key`   | Y | API key for DeepSeek. | `mykey` |
-| `maxToken` | N | The max amount of tokens for each request.  | `2048` |
+| `maxTokens` | N | The max amount of tokens for each request.  | `2048` |
 
 ## Related links