diff --git a/daprdocs/content/en/developing-applications/building-blocks/conversation/howto-conversation-layer.md b/daprdocs/content/en/developing-applications/building-blocks/conversation/howto-conversation-layer.md index 2c33e059516..37cc5764cd5 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/conversation/howto-conversation-layer.md +++ b/daprdocs/content/en/developing-applications/building-blocks/conversation/howto-conversation-layer.md @@ -34,6 +34,28 @@ spec: version: v1 ``` +### Use the OpenAI component + +To interface with a real LLM, use one of the other [supported conversation components]({{< ref "supported-conversation" >}}), including OpenAI, Hugging Face, Anthropic, DeepSeek, and more. + +For example, to swap out the `echo` mock component with an `OpenAI` component, replace the `conversation.yaml` file with the following. You'll need to copy your API key into the component file. + +``` +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: openai +spec: + type: conversation.openai + metadata: + - name: key + value: + - name: model + value: gpt-4-turbo + - name: cacheTTL + value: 10m +``` + ## Connect the conversation client The following examples use an HTTP client to send a POST request to Dapr's sidecar HTTP endpoint. You can also use [the Dapr SDK client instead]({{< ref "#related-links" >}}). diff --git a/daprdocs/content/en/getting-started/quickstarts/conversation-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/conversation-quickstart.md new file mode 100644 index 00000000000..33069f024e7 --- /dev/null +++ b/daprdocs/content/en/getting-started/quickstarts/conversation-quickstart.md @@ -0,0 +1,412 @@ +--- +type: docs +title: "Quickstart: Conversation" +linkTitle: Conversation +weight: 90 +description: Get started with the Dapr conversation building block +--- + +{{% alert title="Alpha" color="warning" %}} +The conversation building block is currently in **alpha**. +{{% /alert %}} + +Let's take a look at how the [Dapr conversation building block]({{< ref conversation-overview.md >}}) makes interacting with Large Language Models (LLMs) easier. In this quickstart, you use the echo component to communicate with the mock LLM and ask it for a poem about Dapr. + +You can try out this conversation quickstart by either: + +- [Running the application in this sample with the Multi-App Run template file]({{< ref "#run-the-app-with-the-template-file" >}}), or +- [Running the application without the template]({{< ref "#run-the-app-without-the-template" >}}) + + +## Run the app with the template file + +{{< tabs ".NET" Go >}} + + +{{% codetab %}} + + +### Step 1: Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- [.NET 8 SDK+ installed](https://dotnet.microsoft.com/download). + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 2: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/conversation). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +From the root of the Quickstarts directory, navigate into the conversation directory: + +```bash +cd conversation/csharp/sdk +``` + +### Step 3: Launch the conversation service + +Start the conversation service with the following command: + +```bash +dapr run -f . +``` + +**Expected output** + +``` +== APP - conversation == Input sent: What is dapr? +== APP - conversation == Output response: What is dapr? +``` + +### What happened? + +When you ran `dapr init` during Dapr install, the [`dapr.yaml` Multi-App Run template file]({{< ref "#dapryaml-multi-app-run-template-file" >}}) was generated in the `.dapr/components` directory. + +Running `dapr run -f .` in this Quickstart started the [conversation Program.cs]({{< ref "#programcs-conversation-app" >}}). + +#### `dapr.yaml` Multi-App Run template file + +Running the [Multi-App Run template file]({{< ref multi-app-dapr-run >}}) with `dapr run -f .` starts all applications in your project. This Quickstart has only one application, so the `dapr.yaml` file contains the following: + +```yml +version: 1 +common: + resourcesPath: ../../components/ +apps: + - appDirPath: ./conversation/ + appID: conversation + daprHTTPPort: 3500 + command: ["dotnet", "run"] +``` + +#### Echo mock LLM component + +In [`conversation/components`](https://github.com/dapr/quickstarts/tree/master/conversation/components), the [`conversation.yaml` file](https://github.com/dapr/quickstarts/tree/master/conversation/components/conversation.yml) configures the echo mock LLM component. + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: echo +spec: + type: conversation.echo + version: v1 +``` + +To interface with a real LLM, swap out the mock component with one of [the supported conversation components]({{< ref "supported-conversation" >}}). For example, to use an OpenAI component, see the [example in the conversation how-to guide]({{< ref "howto-conversation-layer.md#use-the-openai-component" >}}) + +#### `Program.cs` conversation app + +In the application code: +- The app sends an input "What is dapr?" to the echo mock LLM component. +- The mock LLM echoes "What is dapr?". + +```csharp +using Dapr.AI.Conversation; +using Dapr.AI.Conversation.Extensions; + +class Program +{ + private const string ConversationComponentName = "echo"; + + static async Task Main(string[] args) + { + const string prompt = "What is dapr?"; + + var builder = WebApplication.CreateBuilder(args); + builder.Services.AddDaprConversationClient(); + var app = builder.Build(); + + //Instantiate Dapr Conversation Client + var conversationClient = app.Services.GetRequiredService(); + + try + { + // Send a request to the echo mock LLM component + var response = await conversationClient.ConverseAsync(ConversationComponentName, [new(prompt, DaprConversationRole.Generic)]); + Console.WriteLine("Input sent: " + prompt); + + if (response != null) + { + Console.Write("Output response:"); + foreach (var resp in response.Outputs) + { + Console.WriteLine($" {resp.Result}"); + } + } + } + catch (Exception ex) + { + Console.WriteLine("Error: " + ex.Message); + } + } +} +``` + +{{% /codetab %}} + + +{{% codetab %}} + + +### Step 1: Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- [Latest version of Go](https://go.dev/dl/). + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 2: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/conversation). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +From the root of the Quickstarts directory, navigate into the conversation directory: + +```bash +cd conversation/go/sdk +``` + +### Step 3: Launch the conversation service + +Start the conversation service with the following command: + +```bash +dapr run -f . +``` + +**Expected output** + +``` +== APP - conversation == Input sent: What is dapr? +== APP - conversation == Output response: What is dapr? +``` + +### What happened? + +When you ran `dapr init` during Dapr install, the [`dapr.yaml` Multi-App Run template file]({{< ref "#dapryaml-multi-app-run-template-file" >}}) was generated in the `.dapr/components` directory. + +Running `dapr run -f .` in this Quickstart started [conversation.go]({{< ref "#programcs-conversation-app" >}}). + +#### `dapr.yaml` Multi-App Run template file + +Running the [Multi-App Run template file]({{< ref multi-app-dapr-run >}}) with `dapr run -f .` starts all applications in your project. This Quickstart has only one application, so the `dapr.yaml` file contains the following: + +```yml +version: 1 +common: + resourcesPath: ../../components/ +apps: + - appDirPath: ./conversation/ + appID: conversation + daprHTTPPort: 3501 + command: ["go", "run", "."] +``` + +#### Echo mock LLM component + +In [`conversation/components`](https://github.com/dapr/quickstarts/tree/master/conversation/components) directly of the quickstart, the [`conversation.yaml` file](https://github.com/dapr/quickstarts/tree/master/conversation/components/conversation.yml) configures the echo LLM component. + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: echo +spec: + type: conversation.echo + version: v1 +``` + +To interface with a real LLM, swap out the mock component with one of [the supported conversation components]({{< ref "supported-conversation" >}}). For example, to use an OpenAI component, see the [example in the conversation how-to guide]({{< ref "howto-conversation-layer.md#use-the-openai-component" >}}) + +#### `conversation.go` conversation app + +In the application code: +- The app sends an input "What is dapr?" to the echo mock LLM component. +- The mock LLM echoes "What is dapr?". + +```go +package main + +import ( + "context" + "fmt" + "log" + + dapr "github.com/dapr/go-sdk/client" +) + +func main() { + client, err := dapr.NewClient() + if err != nil { + panic(err) + } + + input := dapr.ConversationInput{ + Message: "What is dapr?", + // Role: nil, // Optional + // ScrubPII: nil, // Optional + } + + fmt.Println("Input sent:", input.Message) + + var conversationComponent = "echo" + + request := dapr.NewConversationRequest(conversationComponent, []dapr.ConversationInput{input}) + + resp, err := client.ConverseAlpha1(context.Background(), request) + if err != nil { + log.Fatalf("err: %v", err) + } + + fmt.Println("Output response:", resp.Outputs[0].Result) +} +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Run the app without the template + +{{< tabs ".NET" Go >}} + + +{{% codetab %}} + + +### Step 1: Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- [.NET 8+ SDK installed](https://dotnet.microsoft.com/download). + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 2: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/conversation). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +From the root of the Quickstarts directory, navigate into the conversation directory: + +```bash +cd conversation/csharp/sdk/conversation +``` + +Install the dependencies: + +```bash +dotnet build +``` + +### Step 3: Launch the conversation service + +Start the conversation service with the following command: + +```bash +dapr run --app-id conversation --resources-path ../../../components/ -- dotnet run +``` + +**Expected output** + +``` +== APP - conversation == Input sent: What is dapr? +== APP - conversation == Output response: What is dapr? +``` + +{{% /codetab %}} + + +{{% codetab %}} + + +### Step 1: Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- [Latest version of Go](https://go.dev/dl/). + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 2: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/conversation). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +From the root of the Quickstarts directory, navigate into the conversation directory: + +```bash +cd conversation/go/sdk/conversation +``` + +Install the dependencies: + +```bash +go build . +``` + +### Step 3: Launch the conversation service + +Start the conversation service with the following command: + +```bash +dapr run --app-id conversation --resources-path ../../../components/ -- go run . +``` + +**Expected output** + +``` +== APP - conversation == Input sent: What is dapr? +== APP - conversation == Output response: What is dapr? +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Demo + +Watch the demo presented during [Diagrid's Dapr v1.15 celebration](https://www.diagrid.io/videos/dapr-1-15-deep-dive) to see how the conversation API works using the .NET SDK. + + + +## Tell us what you think! + +We're continuously working to improve our Quickstart examples and value your feedback. Did you find this Quickstart helpful? Do you have suggestions for improvement? + +Join the discussion in our [discord channel](https://discord.com/channels/778680217417809931/953427615916638238). + +## Next steps + +- HTTP samples of this quickstart: + - [Python](https://github.com/dapr/quickstarts/tree/master/conversation/python/http) + - [JavaScript](https://github.com/dapr/quickstarts/tree/master/conversation/javascript/http) + - [.NET](https://github.com/dapr/quickstarts/tree/master/conversation/csharp/http) + - [Go](https://github.com/dapr/quickstarts/tree/master/conversation/go/http) +- Learn more about [the conversation building block]({{< ref conversation-overview.md >}}) + +{{< button text="Explore Dapr tutorials >>" page="getting-started/tutorials/_index.md" >}} diff --git a/daprdocs/content/en/reference/components-reference/supported-conversation/deepseek.md b/daprdocs/content/en/reference/components-reference/supported-conversation/deepseek.md new file mode 100644 index 00000000000..293919d1000 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-conversation/deepseek.md @@ -0,0 +1,39 @@ +--- +type: docs +title: "DeepSeek" +linkTitle: "DeepSeek" +description: Detailed information on the DeepSeek conversation component +--- + +## Component format + +A Dapr `conversation.yaml` component file has the following structure: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: deepseek +spec: + type: conversation.deepseek + metadata: + - name: key + value: mykey + - name: maxTokens + value: 2048 +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| `key` | Y | API key for DeepSeek. | `mykey` | +| `maxToken` | N | The max amount of tokens for each request. | `2048` | + +## Related links + +- [Conversation API overview]({{< ref conversation-overview.md >}}) \ No newline at end of file diff --git a/daprdocs/data/components/conversation/generic.yaml b/daprdocs/data/components/conversation/generic.yaml index 26cf8431ce3..b8961c86829 100644 --- a/daprdocs/data/components/conversation/generic.yaml +++ b/daprdocs/data/components/conversation/generic.yaml @@ -18,3 +18,8 @@ state: Alpha version: v1 since: "1.15" +- component: DeepSeek + link: deepseek + state: Alpha + version: v1 + since: "1.15" diff --git a/daprdocs/static/images/concepts-components.png b/daprdocs/static/images/concepts-components.png index c22c50f2355..62515c4da3e 100644 Binary files a/daprdocs/static/images/concepts-components.png and b/daprdocs/static/images/concepts-components.png differ diff --git a/daprdocs/static/images/conversation-overview.png b/daprdocs/static/images/conversation-overview.png index 5bfa33ddd49..757faea4081 100644 Binary files a/daprdocs/static/images/conversation-overview.png and b/daprdocs/static/images/conversation-overview.png differ