diff --git a/.github/workflows/website-root.yml b/.github/workflows/website-root.yml index dc437b1ca92..c9a5f85edad 100644 --- a/.github/workflows/website-root.yml +++ b/.github/workflows/website-root.yml @@ -4,11 +4,11 @@ on: workflow_dispatch: push: branches: - - v1.15 + - v1.16 pull_request: types: [opened, synchronize, reopened, closed] branches: - - v1.15 + - v1.16 concurrency: # Cancel the previously triggered build for only PR build. @@ -50,23 +50,17 @@ jobs: if [ $GITHUB_EVENT_NAME == 'pull_request' ]; then STAGING_URL="https://${SWA_BASE}-${{github.event.number}}.westus2.azurestaticapps.net/" fi - hugo ${STAGING_URL+-b "$STAGING_URL"} + hugo ${STAGING_URL+-b "$STAGING_URL"} --minify - name: Deploy docs site uses: Azure/static-web-apps-deploy@v1 with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_PROUD_BAY_0E9E0E81E }} repo_token: ${{ secrets.GITHUB_TOKEN }} action: "upload" - app_location: "/daprdocs/public/" + app_location: "/daprdocs/public" output_location: "/" skip_app_build: true skip_deploy_on_missing_secrets: true - - name: Upload Hugo artifacts - uses: actions/upload-artifact@v4 - with: - name: hugo_build - path: ./daprdocs/public/ - if-no-files-found: error close_staging_site: if: github.event_name == 'pull_request' && github.event.action == 'closed' @@ -96,7 +90,7 @@ jobs: with: submodules: false - name: Download Hugo artifacts - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: hugo_build path: site/ diff --git a/README.md b/README.md index 075cc139434..18d2f53b41f 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,8 @@ The following branches are currently maintained: | Branch | Website | Description | | ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ | -| [v1.15](https://github.com/dapr/docs) (primary) | https://docs.dapr.io | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. | -| [v1.16](https://github.com/dapr/docs/tree/v1.16) (pre-release) | https://v1-16.docs.dapr.io/ | Pre-release documentation. Doc updates that are only applicable to v1.15+ go here. | +| [v1.16](https://github.com/dapr/docs) (primary) | https://docs.dapr.io | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. | +| [v1.17](https://github.com/dapr/docs/tree/v1.16) (pre-release) | https://v1-17.docs.dapr.io/ | Pre-release documentation. Doc updates that are only applicable to v1.16+ go here. | For more information visit the [Dapr branch structure](https://docs.dapr.io/contributing/docs-contrib/contributing-docs/#branch-guidance) document. diff --git a/daprdocs/content/en/contributing/docs-contrib/maintainer-guide.md b/daprdocs/content/en/contributing/docs-contrib/maintainer-guide.md index 1ebdfb88172..7c72665b2f0 100644 --- a/daprdocs/content/en/contributing/docs-contrib/maintainer-guide.md +++ b/daprdocs/content/en/contributing/docs-contrib/maintainer-guide.md @@ -103,24 +103,22 @@ These steps will prepare the latest release branch for archival. git checkout -b release_v1.0 ``` -1. In VS Code, navigate to `/daprdocs/config.toml`. -1. Add the following TOML to the `# Versioning` section (around line 154): - - ```toml - version_menu = "v1.0" - version = "v1.0" - archived_version = true - url_latest_version = "https://docs.dapr.io" - - [[params.versions]] - version = "v1.2 (preview)" - url = "v1-2.docs.dapr.io" - [[params.versions]] - version = "v1.1 (latest)" - url = "#" - [[params.versions]] - version = "v1.0" - url = "https://v1-0.docs.dapr.io" +1. In VS Code, navigate to `hugo.yaml` located in the root. +1. Add the following configuration to the `# Versioning` section (around line 121 and onwards): + + ```yaml + version_menu: "v1.0" + version: "v1.0" + archived_version: true + url_latest_version: "https://docs.dapr.io" + + versions: + - version: v1.2 (preview) + url: https://v1-2.docs.dapr.io + - version: v1.1 (latest) + url: "#" + - version: v1.0 + url: https://v1-0.docs.dapr.io ``` 1. Delete `.github/workflows/website-root.yml`. @@ -146,26 +144,25 @@ These steps will prepare the upcoming release branch for promotion to latest rel git checkout -b release_v1.1 ``` -1. In VS Code, navigate to `/daprdocs/config.toml`. -1. Update line 1 to `baseURL - https://docs.dapr.io/`. -1. Update the `# Versioning` section (around line 154) to display the correct versions and tags: +1. In VS Code, navigate to `hugo.yaml` located in the root. +1. Update line 1 to `baseURL: https://docs.dapr.io/`. +1. Update the `# Versioning` section (around line 121 and onwards) to display the correct versions and tags: - ```toml + ```yaml # Versioning - version_menu = "v1.1 (latest)" - version = "v1.1" - archived_version = false - url_latest_version = "https://docs.dapr.io" - - [[params.versions]] - version = "v1.2 (preview)" - url = "v1-2.docs.dapr.io" - [[params.versions]] - version = "v1.1 (latest)" - url = "#" - [[params.versions]] - version = "v1.0" - url = "https://v1-0.docs.dapr.io" + version_menu: "v1.1 (latest)" + version: "v1.1" + archived_version: false + url_latest_version: https://docs.dapr.io + github_branch: v1.1 + + versions: + - version: v1.2 (preview) + url: https://v1-2.docs.dapr.io + - version: v1.1 (latest) + url: "#" + - version: v1.0 + url: https://v1-0.docs.dapr.io ``` 1. Navigate to `.github/workflows/website-root.yml`. @@ -194,6 +191,7 @@ These steps will prepare the upcoming release branch for promotion to latest rel | [v1.2](https://github.com/dapr/docs/tree/v1.2) (pre-release) | https://v1-2.docs.dapr.io/ | Pre-release documentation. Doc updates that are only applicable to v1.2+ go here. | ``` +1. Update the _Supported versions_ table in `support-release-policy.md`; add a new line at the top of the table with the new version of the runtime and SDKs. Change the releases which are older than n-2 to be `Unsupported`. 1. Update the `dapr-latest-version.html` shortcode partial to the new minor/patch version (in this example, `1.1.0` and `1.1`). 1. Commit the staged changes and push to your branch (`release_v1.1`). 1. Open a PR from `release/v1.1` to `v1.1`. diff --git a/daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md b/daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md index 44b0396bf4f..7483a41c296 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md @@ -20,10 +20,10 @@ In addition to enabling critical performance and security functionality (like [p - **OpenAI-compatible interface** for seamless integration with existing AI workflows and tools You can also pair the conversation API with Dapr functionalities, like: -- Resiliency circuit breakers and retries to circumvent limit and token errors, or -- Middleware to authenticate requests coming to and from the LLM -Dapr provides observability by issuing metrics for your LLM interactions. +- Resiliency policies including circuit breakers to handle repeated errors, timeouts to safeguards from slow responses, and retries for temporary network failures +- Observability with metrics and distributed tracing using OpenTelemetry and Zipkin +- Middleware to authenticate requests to and from the LLM ## Features @@ -67,7 +67,7 @@ Watch the demo presented during [Diagrid's Dapr v1.15 celebration](https://www.d {{< youtube id=NTnwoDhHIcQ start=5444 >}} -## Try out conversation +## Try out conversation API ### Quickstarts and tutorials diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md index 36d2df7b3bb..a054393cf56 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md +++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md @@ -197,10 +197,12 @@ public class DemoWorkflowActivity implements WorkflowActivity { +### Define workflow activities + Define each workflow activity you'd like your workflow to perform. The Activity input can be unmarshalled from the context with `ctx.GetInput`. Activities should be defined as taking a `ctx workflow.ActivityContext` parameter and returning an interface and error. ```go -func TestActivity(ctx workflow.ActivityContext) (any, error) { +func BusinessActivity(ctx workflow.ActivityContext) (any, error) { var input int if err := ctx.GetInput(&input); err != nil { return "", err @@ -211,6 +213,87 @@ func TestActivity(ctx workflow.ActivityContext) (any, error) { } ``` +### Define the workflow + +Define your workflow function with the parameter `ctx *workflow.WorkflowContext` and return any and error. Invoke your defined activities from within your workflow. + +```go +func BusinessWorkflow(ctx *workflow.WorkflowContext) (any, error) { + var input int + if err := ctx.GetInput(&input); err != nil { + return nil, err + } + var output string + if err := ctx.CallActivity(BusinessActivity, workflow.ActivityInput(input)).Await(&output); err != nil { + return nil, err + } + if err := ctx.WaitForExternalEvent("businessEvent", time.Second*60).Await(&output); err != nil { + return nil, err + } + + if err := ctx.CreateTimer(time.Second).Await(nil); err != nil { + return nil, nil + } + return output, nil +} +``` + +### Register workflows and activities + +Before your application can execute workflows, you must register both the workflow orchestrator and its activities with a workflow registry. This ensures Dapr knows which functions to call when executing your workflow. + +```go +func main() { + // Create a workflow registry + r := workflow.NewRegistry() + + // Register the workflow orchestrator + if err := r.AddWorkflow(BusinessWorkflow); err != nil { + log.Fatal(err) + } + fmt.Println("BusinessWorkflow registered") + + // Register the workflow activities + if err := r.AddActivity(BusinessActivity); err != nil { + log.Fatal(err) + } + fmt.Println("BusinessActivity registered") + + // Create workflow client and start worker + wclient, err := client.NewWorkflowClient() + if err != nil { + log.Fatal(err) + } + fmt.Println("Worker initialized") + + ctx, cancel := context.WithCancel(context.Background()) + if err = wclient.StartWorker(ctx, r); err != nil { + log.Fatal(err) + } + fmt.Println("runner started") + + // Your application logic continues here... + // Example: Start a workflow + instanceID, err := wclient.ScheduleWorkflow(ctx, "BusinessWorkflow", workflow.WithInput(1)) + if err != nil { + log.Fatalf("failed to start workflow: %v", err) + } + fmt.Printf("workflow started with id: %v\n", instanceID) + + // Stop workflow worker when done + cancel() + fmt.Println("workflow worker successfully shutdown") +} +``` + +**Key points about registration:** +- Use `workflow.NewRegistry()` to create a workflow registry +- Use `r.AddWorkflow()` to register workflow functions +- Use `r.AddActivity()` to register activity functions +- Use `client.NewWorkflowClient()` to create a workflow client +- Call `wclient.StartWorker()` to begin processing workflows +- Use `wclient.ScheduleWorkflow` to schedule a named instance of a workflow + [See the Go SDK workflow activity example in context.](https://github.com/dapr/go-sdk/tree/main/examples/workflow/README.md) {{% /tab %}} @@ -383,16 +466,16 @@ public class DemoWorkflowWorker { Define your workflow function with the parameter `ctx *workflow.WorkflowContext` and return any and error. Invoke your defined activities from within your workflow. ```go -func TestWorkflow(ctx *workflow.WorkflowContext) (any, error) { +func BusinessWorkflow(ctx *workflow.WorkflowContext) (any, error) { var input int if err := ctx.GetInput(&input); err != nil { return nil, err } var output string - if err := ctx.CallActivity(TestActivity, workflow.ActivityInput(input)).Await(&output); err != nil { + if err := ctx.CallActivity(BusinessActivity, workflow.ActivityInput(input)).Await(&output); err != nil { return nil, err } - if err := ctx.WaitForExternalEvent("testEvent", time.Second*60).Await(&output); err != nil { + if err := ctx.WaitForExternalEvent("businessEvent", time.Second*60).Await(&output); err != nil { return nil, err } @@ -864,7 +947,7 @@ public class DemoWorkflow extends Workflow { [As in the following example](https://github.com/dapr/go-sdk/tree/main/examples/workflow/README.md), a hello-world application using the Go SDK and Dapr Workflow would include: - A Go package called `client` to receive the Go SDK client capabilities. -- The `TestWorkflow` method +- The `BusinessWorkflow` method - Creating the workflow with input and output. - API calls. In the example below, these calls start and call the workflow activities. @@ -889,15 +972,15 @@ var failActivityTries = 0 func main() { r := workflow.NewRegistry() - if err := r.AddWorkflow(TestWorkflow); err != nil { + if err := r.AddWorkflow(BusinessWorkflow); err != nil { log.Fatal(err) } - fmt.Println("TestWorkflow registered") + fmt.Println("BusinessWorkflow registered") - if err := r.AddActivity(TestActivity); err != nil { + if err := r.AddActivity(BusinessActivity); err != nil { log.Fatal(err) } - fmt.Println("TestActivity registered") + fmt.Println("BusinessActivity registered") if err := r.AddActivity(FailActivity); err != nil { log.Fatal(err) @@ -921,7 +1004,7 @@ func main() { // "start". This is useful for increasing the throughput of creating // workflows. // workflow.WithStartTime(time.Now()) - instanceID, err := wclient.ScheduleWorkflow(ctx, "TestWorkflow", workflow.WithInstanceID("a7a4168d-3a1c-41da-8a4f-e7f6d9c718d9"), workflow.WithInput(1)) + instanceID, err := wclient.ScheduleWorkflow(ctx, "BusinessWorkflow", workflow.WithInstanceID("a7a4168d-3a1c-41da-8a4f-e7f6d9c718d9"), workflow.WithInput(1)) if err != nil { log.Fatalf("failed to start workflow: %v", err) } @@ -963,9 +1046,8 @@ func main() { fmt.Printf("stage: %d\n", stage) - // Raise Event Test - - err = wclient.RaiseEvent(ctx, instanceID, "testEvent", workflow.WithEventPayload("testData")) + // Raise Event + err = wclient.RaiseEvent(ctx, instanceID, "businessEvent", workflow.WithEventPayload("testData")) if err != nil { fmt.Printf("failed to raise event: %v", err) } @@ -1008,7 +1090,7 @@ func main() { fmt.Printf("stage: %d\n", stage) // Terminate workflow test - id, err := wclient.ScheduleWorkflow(ctx, "TestWorkflow", workflow.WithInstanceID("a7a4168d-3a1c-41da-8a4f-e7f6d9c718d9"), workflow.WithInput(1)) + id, err := wclient.ScheduleWorkflow(ctx, "BusinessWorkflow", workflow.WithInstanceID("a7a4168d-3a1c-41da-8a4f-e7f6d9c718d9"), workflow.WithInput(1)) if err != nil { log.Fatalf("failed to start workflow: %v", err) } @@ -1037,22 +1119,22 @@ func main() { fmt.Println("workflow worker successfully shutdown") } -func TestWorkflow(ctx *workflow.WorkflowContext) (any, error) { +func BusinessWorkflow(ctx *workflow.WorkflowContext) (any, error) { var input int if err := ctx.GetInput(&input); err != nil { return nil, err } var output string - if err := ctx.CallActivity(TestActivity, workflow.WithActivityInput(input)).Await(&output); err != nil { + if err := ctx.CallActivity(BusinessActivity, task.WithActivityInput(input)).Await(&output); err != nil { return nil, err } - err := ctx.WaitForExternalEvent("testEvent", time.Second*60).Await(&output) + err := ctx.WaitForSingleEvent("businessEvent", time.Second*60).Await(&output) if err != nil { return nil, err } - if err := ctx.CallActivity(TestActivity, workflow.WithActivityInput(input)).Await(&output); err != nil { + if err := ctx.CallActivity(BusinessActivity, task.WithActivityInput(input)).Await(&output); err != nil { return nil, err } @@ -1068,7 +1150,7 @@ func TestWorkflow(ctx *workflow.WorkflowContext) (any, error) { return output, nil } -func TestActivity(ctx workflow.ActivityContext) (any, error) { +func BusinessActivity(ctx task.ActivityContext) (any, error) { var input int if err := ctx.GetInput(&input); err != nil { return "", err diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-multi-app.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-multi-app.md index 410b4fc91cd..64f112c7018 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-multi-app.md +++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-multi-app.md @@ -19,28 +19,65 @@ Some scenarios where this is useful include: - Implementation of a workflow spans different programming languages based on team expertise or existing codebases. - Different team boundaries or microservice ownership. +Diagram showing multi-application complex workflow + +The diagram below shows an example scenario of a complex workflow that orchestrates across multiple applications that are written in different languages. Each applications' main steps and activities are: + +• **App1: Main Workflow Service** - Top-level orchestrator that coordinates the entire ML pipeline +- Starts the process +- Calls data processing activities on App2 +- Calls ML training child workflow on App3 +- Calls model deployment on App4 +- Ends the complete workflow +- **Language: Java** + +• **App2: Data Processing Pipeline** - **GPU activities** only +- Data Ingesting Activity (GPU-accelerated) +- Feature Engineering Activity (GPU-accelerated) +- Returns completion signal to Main Workflow +- **Language: Go** + +• **App3: ML Training Child Workflow** - Contains a child workflow and activities +- Child workflow orchestrates: + - Data Processing Activity + - Model Training Activity (GPU-intensive) + - Model Validation Activity +- Triggered by App2's activities completing +- Returns completion signal to Main Workflow +- **Language: Java** + +• **App4: Model Serving Service** - **Beefy GPU app** with activities only +- Model Loading Activity (GPU memory intensive) +- Inference Setup Activity (GPU-accelerated inference) +- Triggered by App3's workflow completing +- Returns completion signal to Main Workflow +- **Language: Go** ## Multi-application workflows -Like all building blocks in Dapr, workflow execution routing is based on the [App ID of the hosting Dapr application]({{% ref "security-concept.md#application-identity" %}}). +Workflow execution routing is based on the [App ID of the hosting Dapr application]({{% ref "security-concept.md#application-identity" %}}). By default, the full workflow execution is hosted on the app ID that started the workflow. This workflow can be executed across any replicas of that app ID, not just the single replica which scheduled the workflow. -It is possible to execute activities or child workflows on different app IDs by specifying the target app ID parameter, inside the workflow execution code. -Upon execution, the target app ID will execute the activity or child workflow, and return the result to the parent workflow of the originating app ID. +It is possible to execute activities and child workflows on different app IDs by specifying the target app ID parameter, inside the workflow execution code. +Upon execution, the target app ID executes the activity or child workflow, and returns the result to the parent workflow of the originating app ID. The entire Workflow execution may be distributed across multiple app IDs with no limit, with each activity or child workflow specifying the target app ID. The final history of the workflow will be saved by the app ID that hosts the very parent (or can consider it the root) workflow. {{% alert title="Restrictions" color="primary" %}} -Like other building blocks and resources in Dapr, workflows are scoped to a single namespace. +Like other API building blocks and resources in Dapr, workflows are scoped to a single namespace. This means that all app IDs involved in a multi-application workflow must be in the same namespace. -Similarly, all app IDs must use the same actor state store. -Finally, the target app ID must have the activity or child workflow defined, otherwise the parent workflow will retry indefinitely. +Similarly, all app IDs must use the same workflow (or actor) state store. +Finally, the target app ID must have the activity or child workflow defined and registered, otherwise the parent workflow retries indefinitely. {{% /alert %}} {{% alert title="Important Limitations" color="warning" %}} -- **SDKs supporting multi-application workflows** - Multi-application workflows are used via the SDKs. Currently Java (activities calling) and Go (both activities and child workflows calling) SDKs are supported. The SDKs (Python, .NET, JavaScript) are planned for future releases. +**SDKs supporting multi-application workflows** - Multi-application workflows are used via the SDKs. +Currently the following are supported: +- **Java** (**only** activity calls) +- **Go** (**both** activities and child workflows calls) +- The Python, .NET, JavaScript SDKs support are planned for future releases {{% /alert %}} ## Error handling @@ -63,7 +100,7 @@ The following example shows how to execute the activity `ActivityA` on the targe {{% tab "Go" %}} ```go -func TestWorkflow(ctx *workflow.WorkflowContext) (any, error) { +func BusinessWorkflow(ctx *workflow.WorkflowContext) (any, error) { var output string err := ctx.CallActivity("ActivityA", workflow.WithActivityInput("my-input"), @@ -83,12 +120,12 @@ func TestWorkflow(ctx *workflow.WorkflowContext) (any, error) { {{% tab "Java" %}} ```java -public class CrossAppWorkflow implements Workflow { +public class BusinessWorkflow implements Workflow { @Override public WorkflowStub create() { return ctx -> { String output = ctx.callActivity( - "ActivityA", + ActivityA.class.getName(), "my-input", new WorkflowTaskOptions("App2"), // Here we set the target app ID which will execute this activity. String.class @@ -115,7 +152,7 @@ The following example shows how to execute the child workflow `Workflow2` on the {{% tab "Go" %}} ```go -func TestWorkflow(ctx *workflow.WorkflowContext) (any, error) { +func BusinessWorkflow(ctx *workflow.WorkflowContext) (any, error) { var output string err := ctx.CallChildWorkflow("Workflow2", workflow.WithChildWorkflowInput("my-input"), diff --git a/daprdocs/content/en/operations/configuration/configuration-overview.md b/daprdocs/content/en/operations/configuration/configuration-overview.md index f501710405c..33cc11d8e31 100644 --- a/daprdocs/content/en/operations/configuration/configuration-overview.md +++ b/daprdocs/content/en/operations/configuration/configuration-overview.md @@ -62,13 +62,14 @@ A Dapr sidecar can apply a specific configuration by using a `dapr.io/config` an ### Application configuration settings -The following menu includes all of the configuration settings you can set on the sidecar. +The following menu includes all of the configuration settings you can set: - [Tracing](#tracing) - [Metrics](#metrics) - [Logging](#logging) - [Middleware](#middleware) - [Name resolution](#name-resolution) +- [Workflow](#workflow) - [Scope secret store access](#scope-secret-store-access) - [Access Control allow lists for building block APIs](#access-control-allow-lists-for-building-block-apis) - [Access Control allow lists for service invocation API](#access-control-allow-lists-for-service-invocation-api) @@ -255,6 +256,15 @@ For more information, see: - [The name resolution component documentation]({{% ref supported-name-resolution %}}) for more examples. - [The Configuration file documentation]({{% ref configuration-schema.md %}}) to learn more about how to configure name resolution per component. +#### Workflow + +The `workflow` section contains properties for configuring [Workflows]({{% ref "workflow-overview.md" %}}). + +| Property | Type | Description | +|------------------|--------|-----| +| `maxConcurrentWorkflowInvocations` | int32 | Maximum number of concurrent workflow executions per Dapr sidecar. Default is infinite. | +| `maxConcurrentActivityInvocations` | int32 | Maximum number of concurrent activity executions per Dapr sidecar. Default is infinite. | + #### Scope secret store access See the [Scoping secrets]({{% ref "secret-scope.md" %}}) guide for information and examples on how to scope secrets to an application. @@ -334,6 +344,9 @@ spec: deny: - bindings.smtp - secretstores.local.file + workflow: + maxConcurrentWorkflowInvocations: 100 + maxConcurrentActivityInvocations: 1000 accessControl: defaultAction: deny trustDomain: "public" diff --git a/daprdocs/content/en/operations/performance-and-scalability/perf-actors-activation.md b/daprdocs/content/en/operations/performance-and-scalability/perf-actors-activation.md index e463ae6c8bf..994e8b7f94c 100644 --- a/daprdocs/content/en/operations/performance-and-scalability/perf-actors-activation.md +++ b/daprdocs/content/en/operations/performance-and-scalability/perf-actors-activation.md @@ -19,9 +19,9 @@ For applications using actors in Dapr there are two aspects to be considered. Fi * Sidecar Injector (control plane) * Sentry (optional, control plane) -## Performance summary for Dapr v1.0 +## Performance summary for Dapr v1.12 -The actors API in Dapr sidecar will identify which hosts are registered for a given actor type and route the request to the appropriate host for a given actor ID. The host runs an instance of the application and uses the Dapr SDK (.Net, Java, Python or PHP) to handle actors requests via HTTP. +The actors API in Dapr sidecar identifies which hosts are registered for a given actor type and routes the request to the appropriate host for a given actor ID. The host runs an instance of the application and uses the Dapr SDK (.Net, Java, Python, Go) to handle actors requests via HTTP. This test uses invokes actors via Dapr's HTTP API directly. @@ -40,17 +40,14 @@ Test parameters: * Sidecar limited to 0.5 vCPU * mTLS enabled * Sidecar telemetry enabled (tracing with a sampling rate of 0.1) -* Payload of an empty JSON object: `{}` ### Results -* The actual throughput was ~500 qps. -* The tp90 latency was ~3ms. -* The tp99 latency was ~6.2ms. -* Dapr app consumed ~523m CPU and ~304.7Mb of Memory -* Dapr sidecar consumed 2m CPU and ~18.2Mb of Memory +* The requested throughput was 500 qps. +* The actual throughput was 500 qps. +* The tp90 latency was ~3.2ms. +* The tp99 latency was ~7ms. +* Dapr app consumed ~339m CPU and ~336Mb of Memory +* Dapr sidecar consumed 93m CPU and ~60Mb of Memory * No app restarts * No sidecar restarts - -## Related links -* For more information see [overview of Dapr on Kubernetes]({{% ref kubernetes-overview.md %}}) \ No newline at end of file diff --git a/daprdocs/content/en/operations/performance-and-scalability/perf-pubsub.md b/daprdocs/content/en/operations/performance-and-scalability/perf-pubsub.md new file mode 100644 index 00000000000..2717bd87db2 --- /dev/null +++ b/daprdocs/content/en/operations/performance-and-scalability/perf-pubsub.md @@ -0,0 +1,50 @@ +--- +type: docs +title: "Pub/sub performance" +linkTitle: "Pub/sub performance" +weight: 30000 +description: "" +--- +This article provides pub/sub API performance benchmarks and resource utilization in Dapr on Kubernetes. + +## System overview + +Dapr consists of a data plane, the sidecar that runs next to your app, and a control plane that configures the sidecars and provides capabilities such as cert and identity management. + +### Kubernetes components + +* Sidecar (data plane) +* Placement (required for actors, control plane mapping actor types to hosts) +* Operator (control plane) +* Sidecar Injector (control plane) +* Sentry (optional, control plane) +* Kafka cluster with 3 replicas + +## Performance summary for Dapr v1.12 + +The Pub/Sub API is used to publish messages to a message broker. Dapr accepts requests from the app via HTTP or gRPC, wraps them in a cloud event if needed, and sends the request to the message broker. + +Performance varies based on the underlying message broker. The Pub/Sub performance test measures the added latency when publishing a message with Dapr compared with the baseline latency when publishing directly to the message broker. + +### Kubernetes performance test setup + +The test was conducted on a 3 node Kubernetes cluster, using commodity hardware running 4 cores and 8GB of RAM, without any network acceleration. + +Test parameters: + +* 1000 requests per second +* 1 replica +* 1 minute duration +* Sidecar limited to 0.5 vCPU +* Sidecar telemetry enabled (tracing with a sampling rate of 0.1) +* Payload of a 1kb size + +### Results + +* The requested throughput was 1000 qps +* The actual throughput was 1000 qps +* Added latency for 90th percentile was 0.64ms for gRPC and 0.49ms for HTTP +* Added latency for 99th percentile was 1.91ms for gRPC and 1.21ms for HTTP +* Dapr app consumed ~0.2 vCPU and ~30Mb of Memory for both gRPC and HTTP +* No app restarts +* No sidecar restarts diff --git a/daprdocs/content/en/operations/performance-and-scalability/perf-service-invocation.md b/daprdocs/content/en/operations/performance-and-scalability/perf-service-invocation.md index fc0816e8620..b50cc6c6174 100644 --- a/daprdocs/content/en/operations/performance-and-scalability/perf-service-invocation.md +++ b/daprdocs/content/en/operations/performance-and-scalability/perf-service-invocation.md @@ -29,7 +29,7 @@ For more information see [overview of Dapr in self-hosted mode]({{% ref self-hos For more information see [overview of Dapr on Kubernetes]({{% ref kubernetes-overview.md %}}). -## Performance summary for Dapr v1.0 +## Performance summary for Dapr v1.12 The service invocation API is a reverse proxy with built-in service discovery to connect to other services. This includes tracing, metrics, mTLS for in-transit encryption of traffic, together with resiliency in the form of retries for network partitions and connection errors. @@ -59,10 +59,10 @@ When running in a highly available production setup, the Dapr control plane cons | Component | vCPU | Memory | ------------- | ------------- | ------------- -| Operator | 0.001 | 12.5 Mb -| Sentry | 0.005 | 13.6 Mb -| Sidecar Injector | 0.002 | 14.6 Mb -| Placement | 0.001 | 20.9 Mb +| Operator | 0.003 | 18 Mb +| Sentry | 0.01 | 33 Mb +| Sidecar Injector | 0.008 | 17 Mb +| Placement | 0.005 | 25 Mb There are a number of variants that affect the CPU and memory consumption for each of the system components. These variants are shown in the table below. @@ -75,18 +75,11 @@ There are a number of variants that affect the CPU and memory consumption for ea ### Data plane performance -The Dapr sidecar uses 0.48 vCPU and 23Mb per 1000 requests per second. -End-to-end, the Dapr sidecars (client and server) add ~1.40 ms to the 90th percentile latency, and ~2.10 ms to the 99th percentile latency. End-to-end here is a call from one app to another app receiving a response. This is shown by steps 1-7 in [this diagram]({{% ref service-invocation-overview.md %}}). - -This performance is on par or better than commonly used service meshes. - -### Latency - In the test setup, requests went through the Dapr sidecar both on the client side (serving requests from the load tester tool) and the server side (the target app). mTLS and telemetry (tracing with a sampling rate of 0.1) and metrics were enabled on the Dapr test, and disabled for the baseline test. -Latency for 90th percentile +The Dapr sidecar uses 0.45 vCPU and 38Mb per 1000 requests per second. -
+End-to-end, the Dapr sidecars (client and server) add ~1.20 ms to the 90th percentile latency, and ~2.50 ms to the 99th percentile latency. End-to-end here is a call from one app to another app receiving a response. This is shown by steps 1-7 in [this diagram]({{< ref service-invocation-overview.md >}}). -Latency for 99th percentile +This performance is on par or better than commonly used service meshes. diff --git a/daprdocs/content/en/operations/performance-and-scalability/perf-state.md b/daprdocs/content/en/operations/performance-and-scalability/perf-state.md new file mode 100644 index 00000000000..8db9d1a4284 --- /dev/null +++ b/daprdocs/content/en/operations/performance-and-scalability/perf-state.md @@ -0,0 +1,50 @@ +--- +type: docs +title: "State performance" +linkTitle: "State performance" +weight: 40000 +description: "" +--- +This article provides state API performance benchmarks and resource utilization in Dapr on Kubernetes. + +## System overview + +Dapr consists of a data plane, the sidecar that runs next to your app, and a control plane that configures the sidecars and provides capabilities such as cert and identity management. + +### Kubernetes components + +* Sidecar (data plane) +* Placement (required for actors, control plane mapping actor types to hosts) +* Operator (control plane) +* Sidecar Injector (control plane) +* Sentry (optional, control plane) +* PosgreSQL database (single node) + +## Performance summary for Dapr v1.12 + +The state API is used to persist state to a database, commonly called state store in Dapr. + +Performance varies based on the underlying state store. The state API performance test measures the added latency when using Dapr to get state compared with the baseline latency when getting state directly from the state store. + +### Kubernetes performance test setup + +The test was conducted on a 3 node Kubernetes cluster, using commodity hardware running 4 cores and 8GB of RAM, without any network acceleration. + +Test parameters: + +* 1000 requests per second +* 1 replica +* 1 minute duration +* Sidecar limited to 0.5 vCPU +* Sidecar telemetry enabled (tracing with a sampling rate of 0.1) +* Payload of a 1kb size + +### Results + +* The requested throughput was 1000 qps +* The actual throughput was 1000 qps +* Added latency for 90th percentile was 0.75ms for gRPC +* Added latency for 99th percentile was 1.52ms for gRPC +* Dapr app consumed ~0.3 vCPU and ~48 of Memory for gRPC +* No app restarts +* No sidecar restarts diff --git a/daprdocs/content/en/operations/support/support-release-policy.md b/daprdocs/content/en/operations/support/support-release-policy.md index 579008b70e0..ff1cd0abe05 100644 --- a/daprdocs/content/en/operations/support/support-release-policy.md +++ b/daprdocs/content/en/operations/support/support-release-policy.md @@ -45,26 +45,27 @@ The table below shows the versions of Dapr releases that have been tested togeth | Release date | Runtime | CLI | SDKs | Dashboard | Status | Release notes | |--------------------|:--------:|:--------|---------|---------|---------|------------| -| July 31st 2025 | 1.15.9
| 1.15.0 | Java 1.14.2, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported (current) | [v1.15.9 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.9) | -| July 18th 2025 | 1.15.8
| 1.15.0 | Java 1.14.2, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported (current) | [v1.15.8 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.8) | -| July 16th 2025 | 1.15.7
| 1.15.0 | Java 1.14.1, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported (current) | [v1.15.7 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.7) | -| June 20th 2025 | 1.15.6
| 1.15.0 | Java 1.14.1, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported (current) | [v1.15.6 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.6) | -| May 5th 2025 | 1.15.5
| 1.15.0 | Java 1.14.1, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported (current) | [v1.15.5 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.5) | -| April 4th 2025 | 1.15.4
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported (current) | [v1.15.4 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.4) | -| March 5rd 2025 | 1.15.3
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported (current) | [v1.15.3 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.3) | -| March 3rd 2025 | 1.15.2
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.0
JS 3.5.0
Rust 0.16 | 0.15.0 | Supported (current) | [v1.15.2 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.2) | -| February 28th 2025 | 1.15.1
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.0
JS 3.5.0
Rust 0.16 | 0.15.0 | Supported (current) | [v1.15.1 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.1) | +| Sep 16th 2025 | 1.16.0
| 1.16.0 | Java 1.15.0
Go 1.13.0
PHP 1.2.0
Python 1.16.0
.NET 1.16.0
JS 3.6.0
Rust 0.17.0 | 0.15.0 | Supported (current) | [v1.16.0 release notes](https://github.com/dapr/dapr/releases/tag/v1.16.0) | +| July 31st 2025 | 1.15.9
| 1.15.0 | Java 1.14.2, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported | [v1.15.9 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.9) | +| July 18th 2025 | 1.15.8
| 1.15.0 | Java 1.14.2, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported | [v1.15.8 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.8) | +| July 16th 2025 | 1.15.7
| 1.15.0 | Java 1.14.1, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported | [v1.15.7 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.7) | +| June 20th 2025 | 1.15.6
| 1.15.0 | Java 1.14.1, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported | [v1.15.6 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.6) | +| May 5th 2025 | 1.15.5
| 1.15.0 | Java 1.14.1, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported | [v1.15.5 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.5) | +| April 4th 2025 | 1.15.4
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported | [v1.15.4 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.4) | +| March 5rd 2025 | 1.15.3
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.4
JS 3.5.2
Rust 0.16.1 | 0.15.0 | Supported | [v1.15.3 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.3) | +| March 3rd 2025 | 1.15.2
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.0
JS 3.5.0
Rust 0.16 | 0.15.0 | Supported | [v1.15.2 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.2) | +| February 28th 2025 | 1.15.1
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.0
JS 3.5.0
Rust 0.16 | 0.15.0 | Supported | [v1.15.1 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.1) | | February 27th 2025 | 1.15.0
| 1.15.0 | Java 1.14.0, 1.15.0
Go 1.12.0
PHP 1.2.0
Python 1.15.0
.NET 1.15.0
JS 3.5.0
Rust 0.16 | 0.15.0 | Supported | [v1.15.0 release notes](https://github.com/dapr/dapr/releases/tag/v1.15.0) | | September 16th 2024 | 1.14.4
| 1.14.1 | Java 1.12.0
Go 1.11.0
PHP 1.2.0
Python 1.14.0
.NET 1.14.0
JS 3.3.1 | 0.15.0 | Supported | [v1.14.4 release notes](https://github.com/dapr/dapr/releases/tag/v1.14.4) | | September 13th 2024 | 1.14.3
| 1.14.1 | Java 1.12.0
Go 1.11.0
PHP 1.2.0
Python 1.14.0
.NET 1.14.0
JS 3.3.1 | 0.15.0 | ⚠️ Recalled | [v1.14.3 release notes](https://github.com/dapr/dapr/releases/tag/v1.14.3) | | September 6th 2024 | 1.14.2
| 1.14.1 | Java 1.12.0
Go 1.11.0
PHP 1.2.0
Python 1.14.0
.NET 1.14.0
JS 3.3.1 | 0.15.0 | Supported | [v1.14.2 release notes](https://github.com/dapr/dapr/releases/tag/v1.14.2) | | August 14th 2024 | 1.14.1
| 1.14.1 | Java 1.12.0
Go 1.11.0
PHP 1.2.0
Python 1.14.0
.NET 1.14.0
JS 3.3.1 | 0.15.0 | Supported | [v1.14.1 release notes](https://github.com/dapr/dapr/releases/tag/v1.14.1) | | August 14th 2024 | 1.14.0
| 1.14.0 | Java 1.12.0
Go 1.11.0
PHP 1.2.0
Python 1.14.0
.NET 1.14.0
JS 3.3.1 | 0.15.0 | Supported | [v1.14.0 release notes](https://github.com/dapr/dapr/releases/tag/v1.14.0) | -| May 29th 2024 | 1.13.4
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Supported | [v1.13.4 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.4) | -| May 21st 2024 | 1.13.3
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Supported | [v1.13.3 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.3) | -| April 3rd 2024 | 1.13.2
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Supported | [v1.13.2 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.2) | -| March 26th 2024 | 1.13.1
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Supported | [v1.13.1 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.1) | -| March 6th 2024 | 1.13.0
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Supported | [v1.13.0 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.0) | +| May 29th 2024 | 1.13.4
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Unsupported | [v1.13.4 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.4) | +| May 21st 2024 | 1.13.3
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Unsupported | [v1.13.3 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.3) | +| April 3rd 2024 | 1.13.2
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Unsupported | [v1.13.2 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.2) | +| March 26th 2024 | 1.13.1
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Unsupported | [v1.13.1 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.1) | +| March 6th 2024 | 1.13.0
| 1.13.0 | Java 1.11.0
Go 1.10.0
PHP 1.2.0
Python 1.13.0
.NET 1.13.0
JS 3.3.0 | 0.14.0 | Unsupported | [v1.13.0 release notes](https://github.com/dapr/dapr/releases/tag/v1.13.0) | | January 17th 2024 | 1.12.4
| 1.12.0 | Java 1.10.0
Go 1.9.1
PHP 1.2.0
Python 1.12.0
.NET 1.12.0
JS 3.2.0 | 0.14.0 | Unsupported | [v1.12.4 release notes](https://github.com/dapr/dapr/releases/tag/v1.12.4) | | January 2nd 2024 | 1.12.3
| 1.12.0 | Java 1.10.0
Go 1.9.1
PHP 1.2.0
Python 1.12.0
.NET 1.12.0
JS 3.2.0 | 0.14.0 | Unsupported | [v1.12.3 release notes](https://github.com/dapr/dapr/releases/tag/v1.12.3) | | November 18th 2023 | 1.12.2
| 1.12.0 | Java 1.10.0
Go 1.9.1
PHP 1.2.0
Python 1.12.0
.NET 1.12.0
JS 3.2.0 | 0.14.0 | Unsupported | [v1.12.2 release notes](https://github.com/dapr/dapr/releases/tag/v1.12.2) | diff --git a/daprdocs/content/en/reference/api/conversation_api.md b/daprdocs/content/en/reference/api/conversation_api.md index 43c62b91f58..eab64dd6ed5 100644 --- a/daprdocs/content/en/reference/api/conversation_api.md +++ b/daprdocs/content/en/reference/api/conversation_api.md @@ -12,7 +12,7 @@ The conversation API is currently in [alpha]({{% ref "certification-lifecycle.md Dapr provides an API to interact with Large Language Models (LLMs) and enables critical performance and security functionality with features like prompt caching, PII data obfuscation, and tool calling capabilities. -Tool calling follow's OpenAI's function calling format, making it easy to integrate with existing AI development workflows and tools. +Tool calling follows OpenAI's function calling format, making it easy to integrate with existing AI development workflows and tools. ## Converse @@ -32,11 +32,10 @@ POST http://localhost:/v1.0-alpha2/conversation//converse | Field | Description | | --------- | ----------- | -| `name` | The name of the conversation component. Required | | `contextId` | The ID of an existing chat (like in ChatGPT). Optional | | `inputs` | Inputs for the conversation. Multiple inputs at one time are supported. Required | | `parameters` | Parameters for all custom fields. Optional | -| `metadata` | [Metadata](#metadata) passed to conversation components. Optional | +| `metadata` | Metadata passed to conversation components. Optional | | `scrubPii` | A boolean value to enable obfuscation of sensitive information returning from the LLM. Optional | | `temperature` | A float value to control the temperature of the model. Used to optimize for consistency (0) or creativity (1). Optional | | `tools` | Tools register the tools available to be used by the LLM during the conversation. Optional | @@ -53,11 +52,14 @@ POST http://localhost:/v1.0-alpha2/conversation//converse The API supports different message types: -- **`ofDeveloper`**: Developer role messages with optional name and content -- **`ofSystem`**: System role messages with optional name and content -- **`ofUser`**: User role messages with optional name and content -- **`ofAssistant`**: Assistant role messages with optional name, content, and tool calls -- **`ofTool`**: Tool role messages with tool ID, name, and content +| Type | Description | +| ---- | ----------- | +| `ofDeveloper` | Developer role messages with optional name and content | +| `ofSystem` | System role messages with optional name and content | +| `ofUser` | User role messages with optional name and content | +| `ofAssistant` | Assistant role messages with optional name, content, and tool calls | +| `ofTool` | Tool role messages with tool ID, name, and content | + #### Tool calling @@ -69,81 +71,136 @@ Tools can be defined using the `tools` field with function definitions: | `function.description` | A description of what the function does. Optional | | `function.parameters` | JSON Schema object describing the function parameters. Optional | + +#### Tool choice options + +The `toolChoice` is an optional parameter that controls how the model can use available tools: + +- **`auto`**: The model can pick between generating a message or calling one or more tools (default when tools are present) +- **`required`**: Requires one or more functions to be called +- **`{tool_name}`**: Forces the model to call a specific tool by name + + +#### Metadata +The `metadata` field serves as a dynamic configuration mechanism that allows you to pass additional configuration and authentication information to conversation components on a per-request basis. This metadata overrides any corresponding fields configured in the component's YAML configuration file, enabling dynamic configuration without modifying static component definitions. + +**Common metadata fields:** + +| Field | Description | Example | +| ----- | ----------- | ------- | +| `api_key` | API key for authenticating with the LLM service | `"sk-1234567890abcdef"` | +| `model` | Specific model identifier | `"gpt-4-turbo"`, `"claude-3-sonnet"` | +| `version` | API version or service version | `"1.0"`, `"2023-12-01"` | +| `endpoint` | Custom endpoint URL for the service | `"https://api.custom-llm.com/v1"` | + +{{% alert title="Note" color="primary" %}} +The exact metadata fields supported depend on the specific conversation component implementation. Refer to the component's documentation for the complete list of supported metadata fields. +{{% /alert %}} + +In addition to passing metadata in the request body, you can also pass metadata as URL query parameters without modifying the request payload. Here is the format: + +- **Prefix**: All metadata parameters must be prefixed with `metadata.` +- **Format**: `?metadata.=` +- **Multiple parameters**: Separate with `&` (e.g., `?metadata.api_key=sk-123&metadata.model=gpt-4`) + +Example of model override: +```bash +POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse?metadata.model=sk-gpt-4-turbo +``` + +URL metadata parameters are merged with request body metadata, URL parameters take precedence if conflicts exist, and both override component configuration in the YAML file. + ### Request content examples #### Basic conversation ```json -REQUEST = { - "name": "openai", - "inputs": [{ - "messages": [{ - "of_user": { - "content": [{ - "text": "What is Dapr?" - }] - } - }] - }], - "parameters": {}, - "metadata": {} -} +curl -X POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse \ + -H "Content-Type: application/json" \ + -d '{ + "inputs": [ + { + "messages": [ + { + "ofUser": { + "content": [ + { + "text": "What is Dapr?" + } + ] + } + } + ] + } + ], + "parameters": {}, + "metadata": {} + }' ``` #### Conversation with tool calling ```json -{ - "name": "openai", - "inputs": [{ - "messages": [{ - "of_user": { - "content": [{ - "text": "What is the weather like in San Francisco in celsius?" - }] - } - }], - "scrub_pii": false - }], - "parameters": { - "max_tokens": { - "@type": "type.googleapis.com/google.protobuf.Int64Value", - "value": "100" - }, - "model": { - "@type": "type.googleapis.com/google.protobuf.StringValue", - "value": "claude-3-5-sonnet-20240620" - } - }, - "metadata": { - "api_key": "test-key", - "version": "1.0" - }, - "scrub_pii": false, - "temperature": 0.7, - "tools": [{ - "function": { - "name": "get_weather", - "description": "Get the current weather for a location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" +curl -X POST http://localhost:3500/v1.0-alpha2/conversation/openai/converse \ + -H "Content-Type: application/json" \ + -d '{ + "inputs": [ + { + "messages": [ + { + "ofUser": { + "content": [ + { + "text": "What is the weather like in San Francisco in celsius?" + } + ] + } + } + ], + "scrubPii": false + } + ], + "parameters": { + "max_tokens": { + "@type": "type.googleapis.com/google.protobuf.Int64Value", + "value": "100" }, - "unit": { - "type": "string", - "enum": ["celsius", "fahrenheit"], - "description": "The temperature unit to use" + "model": { + "@type": "type.googleapis.com/google.protobuf.StringValue", + "value": "claude-3-5-sonnet-20240620" } }, - "required": ["location"] - } - } - }], - "tool_choice": "auto" -} + "metadata": { + "api_key": "test-key", + "version": "1.0" + }, + "scrubPii": false, + "temperature": 0.7, + "tools": [ + { + "function": { + "name": "get_weather", + "description": "Get the current weather for a location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"], + "description": "The temperature unit to use" + } + }, + "required": ["location"] + } + } + } + ], + "toolChoice": "auto" + }' ``` ### HTTP response codes @@ -159,17 +216,19 @@ Code | Description #### Basic conversation response ```json -RESPONSE = { - "outputs": [{ - "choices": [{ - "finish_reason": "stop", - "index": 0, - "message": { - "content": "Dapr is a distributed application runtime that makes it easy for developers to build resilient, stateless and stateful applications that run on the cloud and edge.", - "tool_calls": [] - } - }] - }] +{ + "outputs": [ + { + "choices": [ + { + "finishReason": "stop", + "message": { + "content": "Distributed application runtime, open-source." + } + } + ] + } + ] } ``` @@ -177,32 +236,29 @@ RESPONSE = { ```json { - "outputs": [{ - "choices": [{ - "finish_reason": "tool_calls", - "index": 0, - "message": { - "content": null, - "tool_calls": [{ - "id": "call_123", - "function": { - "name": "get_weather", - "arguments": "{\"location\": \"San Francisco, CA\", \"unit\": \"celsius\"}" + "outputs": [ + { + "choices": [ + { + "finishReason": "tool_calls", + "message": { + "toolCalls": [ + { + "id": "call_Uwa41pG0UqGA2zp0Fec0KwOq", + "function": { + "name": "get_weather", + "arguments": "{\"location\":\"San Francisco, CA\",\"unit\":\"celsius\"}" + } + } + ] } - }] - } - }] - }] + } + ] + } + ] } ``` -### Tool choice options - -The `tool_choice` is an optional parameter that controls how the model can use available tools: - -- **`auto`**: The model can pick between generating a message or calling one or more tools (default when tools are present) -- **`required`**: Requires one or more functions to be called -- **`{tool_name}`**: Forces the model to call a specific tool by name ## Legacy Alpha1 API diff --git a/daprdocs/content/en/reference/components-reference/supported-conversation/openai.md b/daprdocs/content/en/reference/components-reference/supported-conversation/openai.md index 795f9877909..f1c29e2b5f3 100644 --- a/daprdocs/content/en/reference/components-reference/supported-conversation/openai.md +++ b/daprdocs/content/en/reference/components-reference/supported-conversation/openai.md @@ -46,6 +46,48 @@ The above example uses secrets as plain strings. It is recommended to use a secr | `apiType` | N | Specifies the API provider type. Required when using a provider that does not follow the default OpenAI API endpoint conventions. | `azure` | | `apiVersion`| N | The API version to use. Required when the `apiType` is set to `azure`. | `2025-04-01-preview` | +## Azure OpenAI Configuration + +To configure the OpenAI component to connect to Azure OpenAI, you need to set the following metadata fields which are required for Azure's API format. + +### Required fields for Azure OpenAI + +When connecting to Azure OpenAI, the following fields are **required**: + +- `apiType`: Must be set to `azure` to enable Azure OpenAI compatibility +- `endpoint`: Your Azure OpenAI resource endpoint URL (e.g., `https://your-resource.openai.azure.com/`) +- `apiVersion`: The API version for your Azure OpenAI deployment (e.g., `2025-01-01-preview`) +- `key`: Your Azure OpenAI API key + +Get your configuration values from: https://ai.azure.com/ + +### Azure OpenAI component example + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: azure-openai +spec: + type: conversation.openai + metadata: + - name: key + value: "your-azure-openai-api-key" + - name: model + value: "gpt-4.1-nano" # Default: gpt-4.1-nano + - name: endpoint + value: "https://your-resource.openai.azure.com/" + - name: apiType + value: "azure" + - name: apiVersion + value: "2025-01-01-preview" +``` + + +{{% alert title="Note" color="primary" %}} +When using Azure OpenAI, both `endpoint` and `apiVersion` are mandatory fields. The component returns an error if either field is missing when `apiType` is set to `azure`. +{{% /alert %}} + ## Related links - [Conversation API overview]({{% ref conversation-overview.md %}}) diff --git a/daprdocs/layouts/_shortcodes/dapr-latest-version.html b/daprdocs/layouts/_shortcodes/dapr-latest-version.html index a085fd0e6f5..bdd712552d8 100644 --- a/daprdocs/layouts/_shortcodes/dapr-latest-version.html +++ b/daprdocs/layouts/_shortcodes/dapr-latest-version.html @@ -1 +1 @@ -{{- if .Get "short" }}1.15{{ else if .Get "long" }}1.15.5{{ else if .Get "cli" }}1.15.1{{ else }}1.15.1{{ end -}} +{{- if .Get "short" }}1.16{{ else if .Get "long" }}1.16.0{{ else if .Get "cli" }}1.16.0{{ else }}1.16.0{{ end -}} diff --git a/daprdocs/static/images/workflow-overview/workflow-multi-app-child-workflow.png b/daprdocs/static/images/workflow-overview/workflow-multi-app-child-workflow.png index 5d5cec79b38..388fcc8cf27 100644 Binary files a/daprdocs/static/images/workflow-overview/workflow-multi-app-child-workflow.png and b/daprdocs/static/images/workflow-overview/workflow-multi-app-child-workflow.png differ diff --git a/daprdocs/static/images/workflow-overview/workflow-multi-app-complex.png b/daprdocs/static/images/workflow-overview/workflow-multi-app-complex.png new file mode 100644 index 00000000000..8a2c401f89a Binary files /dev/null and b/daprdocs/static/images/workflow-overview/workflow-multi-app-complex.png differ diff --git a/hugo.yaml b/hugo.yaml index a6e206f75ee..980529773db 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -1,4 +1,4 @@ -baseURL: https://v1-16.docs.dapr.io +baseURL: https://docs.dapr.io title: Dapr Docs # Output directory for generated site @@ -117,21 +117,22 @@ params: # First one is picked as the Twitter card image if not set on page. # images: [images/project-illustration.png] - + + # Versioning # Menu title if your navbar has a versions selector to access old versions of your site. # This menu appears only if you have at least one [params.versions] set. - version_menu: v1.16 (preview) - - # Flag used in the "version-banner" partial to decide whether to display a - # banner on every page indicating that this is an archived version of the docs. - # Set this flag to "true" if you want to display the banner. - archived_version: false + version_menu: v1.16 (latest) # The version number for the version of the docs represented in this doc set. # Used in the "version-banner" partial to display a version number for the # current doc set. version: v1.16 + # Flag used in the "version-banner" partial to decide whether to display a + # banner on every page indicating that this is an archived version of the docs. + # Set this flag to "true" if you want to display the banner. + archived_version: false + # A link to latest version of the docs. Used in the "version-banner" partial to # point people to the main doc site. url_latest_version: https://docs.dapr.io @@ -150,10 +151,12 @@ params: github_branch: v1.16 versions: - - version: v1.16 (preview) + - version: v1.17 (preview) + url: https://v1-17.docs.dapr.io + - version: v1.16 (latest) url: "#" - - version: v1.15 (latest) - url: "https://docs.dapr.io" + - version: v1.15 + url: https://v1-15.docs.dapr.io - version: v1.14 url: https://v1-14.docs.dapr.io - version: v1.13