From 399c075fb8f7beaadf4d75bf6026b7b1c0aea5b4 Mon Sep 17 00:00:00 2001 From: Han Wang Date: Mon, 4 Dec 2023 17:45:19 +0800 Subject: [PATCH] [Doc] Add flow as func doc (#1353) This pull request adds a new guide to the documentation on how to execute a flow as a function. The guide explains how to load and invoke a flow as a function in code, configure the flow with context, override flow inputs, and use streaming output. ![image](https://github.com/microsoft/promptflow/assets/7776147/aebfa891-3b70-4eb5-861d-0189dbacc8a4) * `docs/how-to-guides/index.md`: Added a new guide on how to execute a flow as a function. * `docs/how-to-guides/execute-flow-as-a-function.md`: Added a new guide explaining how to load and invoke a flow as a function in code, configure the flow with context, override flow inputs, and use streaming output.# Description Please add an informative description that covers that changes made by the pull request and link all relevant issues. # All Promptflow Contribution checklist: - [ ] **The pull request does not introduce [breaking changes].** - [ ] **CHANGELOG is updated for new features, bug fixes or other significant changes.** - [ ] **I have read the [contribution guidelines](../CONTRIBUTING.md).** - [ ] **Create an issue and link to the pull request to get dedicated review from promptflow team. Learn more: [suggested workflow](../CONTRIBUTING.md#suggested-workflow).** ## General Guidelines and Best Practices - [ ] Title of the pull request is clear and informative. - [ ] There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, [see this page](https://github.com/Azure/azure-powershell/blob/master/documentation/development-docs/cleaning-up-commits.md). ### Testing Guidelines - [ ] Pull request includes test coverage for the included changes. --- .../execute-flow-as-a-function.md | 92 +++++++++++++++++++ docs/how-to-guides/index.md | 1 + 2 files changed, 93 insertions(+) create mode 100644 docs/how-to-guides/execute-flow-as-a-function.md diff --git a/docs/how-to-guides/execute-flow-as-a-function.md b/docs/how-to-guides/execute-flow-as-a-function.md new file mode 100644 index 00000000000..a3aaab1988c --- /dev/null +++ b/docs/how-to-guides/execute-flow-as-a-function.md @@ -0,0 +1,92 @@ +# Execute flow as a function + +:::{admonition} Experimental feature +This is an experimental feature, and may change at any time. Learn [more](faq.md#stable-vs-experimental). +::: + +## Overview + +Promptflow allows you to load a flow and use it as a function in your code. +This feature is useful when building a service on top of a flow, reference [here](https://github.com/microsoft/promptflow/tree/main/examples/tutorials/flow-deploy/create-service-with-flow) for a simple example service with flow function consumption. + +## Load an invoke the flow function + +To use the flow-as-function feature, you first need to load a flow using the `load_flow` function. +Then you can consume the flow object like a function by providing key-value arguments for it. + +```python +f = load_flow("../../examples/flows/standard/web-classification/") +f(url="sample_url") +``` + +## Config the flow with context + +You can overwrite some flow configs before flow function execution by setting `flow.context`. + +### Load flow as a function with in-memory connection override + +By providing a connection object to flow context, flow won't need to get connection in execution time, which can save time when for cases where flow function need to be called multiple times. + +```python +from promptflow.entities import AzureOpenAIConnection + +connection_obj = AzureOpenAIConnection( + name=conn_name, + api_key=api_key, + api_base=api_base, + api_type="azure", + api_version=api_version, +) +# no need to create the connection object. +f.context = FlowContext( + connections={"classify_with_llm": {"connection": connection_obj}} +) +``` + +### Local flow as a function with flow inputs override + +By providing overrides, the original flow dag will be updated in execution time. + +```python +f.context = FlowContext( + # node "fetch_text_content_from_url" will take inputs from the following command instead of from flow input + overrides={"nodes.fetch_text_content_from_url.inputs.url": sample_url}, +) +``` + +**Note**, the `overrides` are only doing YAML content replacement on original `flow.dag.yaml`. +If the `flow.dag.yaml` become invalid after `overrides`, validation error will be raised when executing. + +### Load flow as a function with streaming output + +After set `streaming` in flow context, the flow function will return an iterator to stream the output. + +```python +f = load_flow(source="../../examples/flows/chat/basic-chat/") +f.context.streaming = True +result = f( + chat_history=[ + { + "inputs": {"chat_input": "Hi"}, + "outputs": {"chat_output": "Hello! How can I assist you today?"}, + } + ], + question="How are you?", +) + + +answer = "" +# the result will be a generator, iterate it to get the result +for r in result["answer"]: + answer += r + +``` + +Reference our [sample](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/get-started/flow-as-function.ipynb) for usage. + +## Next steps + +Learn more about: + +- [Flow as a function sample](https://github.com/microsoft/promptflow/blob/main/examples/tutorials/get-started/flow-as-function.ipynb) +- [Deploy a flow](./deploy-a-flow/index.md) diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 0b6afeede5b..2d83790850b 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -10,6 +10,7 @@ init-and-test-a-flow add-conditional-control-to-a-flow run-and-evaluate-a-flow/index tune-prompts-with-variants +execute-flow-as-a-function deploy-a-flow/index enable-streaming-mode manage-connections