From 9a2e489893ba19638ac34ec617c0d1468519146c Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Thu, 13 Feb 2025 15:38:29 -0500 Subject: [PATCH 1/6] add metadata fields to api reference doc Signed-off-by: Hannah Hunter --- .../content/en/reference/api/conversation_api.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index 366625006de..cfe7e7decce 100644 --- a/daprdocs/content/en/reference/api/conversation_api.md +++ b/daprdocs/content/en/reference/api/conversation_api.md @@ -30,9 +30,10 @@ POST /v1.0-alpha1/conversation//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. | +| `parameters` | Parameters for all custom fields. | +| `metadata` | Metadata passed to conversation components. Values include `model`, `key`, `endpoint`, and `cacheTTL` | ### Request content @@ -41,6 +42,12 @@ POST /v1.0-alpha1/conversation//converse REQUEST = { "inputs": ["what is Dapr", "Why use Dapr"], "parameters": {}, + "metadata": { + "model": "model-ID-string-based-on-component-used", + "key": "key1", + "cacheTTL": "10m", + "endpoint": "http://localhost:3500" + } } ``` From e5c0ad3b2a408f75a01375a84d6cccb286de9cb8 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Fri, 14 Feb 2025 12:57:08 -0500 Subject: [PATCH 2/6] updates from Yaron Signed-off-by: Hannah Hunter --- .../content/en/reference/api/conversation_api.md | 14 ++++++++++++-- .../supported-conversation/aws-bedrock.md | 4 ++++ .../supported-conversation/deepseek.md | 2 +- 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index cfe7e7decce..86c2e32bed3 100644 --- a/daprdocs/content/en/reference/api/conversation_api.md +++ b/daprdocs/content/en/reference/api/conversation_api.md @@ -32,9 +32,19 @@ POST /v1.0-alpha1/conversation//converse | --------- | ----------- | | `conversationContext` | The ID of an existing chat room (like in ChatGPT). | | `inputs` | Inputs for the conversation. Multiple inputs at one time are supported. | -| `parameters` | Parameters for all custom fields. | -| `metadata` | Metadata passed to conversation components. Values include `model`, `key`, `endpoint`, and `cacheTTL` | +| `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. | + +The metadata parameters available depend on the conversation component you use. [See all the supported components for the conversation API.]({{< ref supported-conversation >}}) ### Request content diff --git a/daprdocs/content/en/reference/components-reference/supported-conversation/aws-bedrock.md b/daprdocs/content/en/reference/components-reference/supported-conversation/aws-bedrock.md index 759e370134d..d1b5f2dd128 100644 --- a/daprdocs/content/en/reference/components-reference/supported-conversation/aws-bedrock.md +++ b/daprdocs/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 >}}) \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-conversation/deepseek.md b/daprdocs/content/en/reference/components-reference/supported-conversation/deepseek.md index 293919d1000..e09148dafcc 100644 --- a/daprdocs/content/en/reference/components-reference/supported-conversation/deepseek.md +++ b/daprdocs/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 From e9886d53b4f7c351cd7156a082f5aadc0eeaa344 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Fri, 14 Feb 2025 13:08:22 -0500 Subject: [PATCH 3/6] some edits Signed-off-by: Hannah Hunter --- .../content/en/reference/api/conversation_api.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index 86c2e32bed3..3550b63e9e6 100644 --- 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//converse +POST http://localhost:/v1.0-alpha1/conversation//converse ``` ### URL parameters @@ -44,7 +44,15 @@ Metadata can be sent in the request’s URL. It must be prefixed with `metadata. | `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 @@ -56,7 +64,6 @@ REQUEST = { "model": "model-ID-string-based-on-component-used", "key": "key1", "cacheTTL": "10m", - "endpoint": "http://localhost:3500" } } ``` @@ -67,7 +74,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 @@ -88,4 +95,5 @@ RESPONSE = { ## Next steps -[Conversation API overview]({{< ref conversation-overview.md >}}) \ No newline at end of file +- [Conversation API overview]({{< ref conversation-overview.md >}}) +- [Supported conversation components]({{< ref supported-conversation >}}) \ No newline at end of file From e50f948740e3bff9e222046bbf09643d376fb240 Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Fri, 14 Feb 2025 14:27:46 -0500 Subject: [PATCH 4/6] Update daprdocs/content/en/reference/api/conversation_api.md Co-authored-by: Mark Fussell Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- daprdocs/content/en/reference/api/conversation_api.md | 1 - 1 file changed, 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index 3550b63e9e6..3c59089173a 100644 --- a/daprdocs/content/en/reference/api/conversation_api.md +++ b/daprdocs/content/en/reference/api/conversation_api.md @@ -59,7 +59,6 @@ The metadata parameters available depend on the conversation component you use. ```json REQUEST = { "inputs": ["what is Dapr", "Why use Dapr"], - "parameters": {}, "metadata": { "model": "model-ID-string-based-on-component-used", "key": "key1", From 38f37a1f9ee89ec129f0540bc6f05a0b10956c67 Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Fri, 14 Feb 2025 14:28:02 -0500 Subject: [PATCH 5/6] Update daprdocs/content/en/reference/api/conversation_api.md Co-authored-by: Mark Fussell Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- daprdocs/content/en/reference/api/conversation_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index 3c59089173a..eeff733f441 100644 --- a/daprdocs/content/en/reference/api/conversation_api.md +++ b/daprdocs/content/en/reference/api/conversation_api.md @@ -61,7 +61,7 @@ REQUEST = { "inputs": ["what is Dapr", "Why use Dapr"], "metadata": { "model": "model-ID-string-based-on-component-used", - "key": "key1", + "key": "authKey", "cacheTTL": "10m", } } From 86a91341aa709ff0045f1b6d2f4058511ca2965b Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Fri, 14 Feb 2025 14:28:09 -0500 Subject: [PATCH 6/6] Update daprdocs/content/en/reference/api/conversation_api.md Co-authored-by: Mark Fussell Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- daprdocs/content/en/reference/api/conversation_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index eeff733f441..7f022134fa2 100644 --- a/daprdocs/content/en/reference/api/conversation_api.md +++ b/daprdocs/content/en/reference/api/conversation_api.md @@ -60,7 +60,7 @@ The metadata parameters available depend on the conversation component you use. REQUEST = { "inputs": ["what is Dapr", "Why use Dapr"], "metadata": { - "model": "model-ID-string-based-on-component-used", + "model": "model-type-based-on-component-used", "key": "authKey", "cacheTTL": "10m", }