update

microsoft · Apr 25, 2024 · 9d96ff7 · 9d96ff7
1 parent 8491d17
commit 9d96ff7
Show file tree

Hide file tree

Showing 4 changed files with 95 additions and 70 deletions.
diff --git a/docs/how-to-guides/develop-a-flex-flow/class-based-flow.md b/docs/how-to-guides/develop-a-flex-flow/class-based-flow.md
@@ -9,9 +9,11 @@ When user need to persist objects (like connection) in memory during multiple ro
 If user need to log metrics on batch run outputs, they can add an `__aggregate__` method and it will be scheduled after batch run finishes.
 The `__aggregate__` method should only contain 1 params which is list of batch run results.
 
-See [connection support](#connection-support) & [aggregation support](#aggregation-support-metrics) for more details.
+See [connection support](#connection-support) & [aggregation support](#aggregation-support) for more details.
 
-## Authoring
+## Class as a flow
+
+Assume we have a file `flow_entry.py`:
 
 ```python
 class Reply(TypedDict):
@@ -23,7 +25,7 @@ class MyFlow:
       self.model_config = model_config
       self.flow_config = flow_config
 
-    def __call__(text: str) -> Reply:
+    def __call__(question: str) -> Reply:
       """Flow execution logic goes here."""
       return Reply(output=output)
 
@@ -32,15 +34,6 @@ class MyFlow:
       return {"key": val}
 ```
 
-## YAML support
-
-User can write a YAML file with name `flow.flex.yaml` manually or save a function/callable entry to YAML file.
-A flow YAML may look like this:
-
-```yaml
-$schema: https://azuremlschemas.azureedge.net/promptflow/latest/Flow.schema.json
-entry: path.to.module:ClassName
-```
 
 ## Flow test
 
@@ -50,26 +43,33 @@ Since flow's definition is function/callable class. We recommend user directly r
 class MyFlow:
     pass
 if __name__ == "__main__":
-    flow = MyFlow(**init_args)
-    output = flow(**call_args)
+    flow = MyFlow(model_config, flow_config)
+    output = flow(question)
     metrics = flow.__aggregate__([output])
     # check metrics here
 ```
 
-## Chat with a flow
+You can also test the flow using CLI:
+```bash
+# flow entry syntax: path.to.module:ClassName
+pf flow test --flow flow_entry:MyFlow --inputs question="What's the capital of France?" --init init.json
+```
+
+Check out a full example here: [basic-chat](https://github.com/microsoft/promptflow/tree/main/examples/flex-flows/basic-chat)
+
+### Chat with a flow
 
 Chat with flow in CLI is supported:
 
 ```bash
-pf flow test --flow path/to/flow --inputs path/to/inputs --init path/to/init --ui
+pf flow test --flow flow_entry:MyFlow --inputs inputs.json --init init.json --ui
 ```
 
 Check [here](../chat-with-a-flow/index.md) for more information.
 
-## Batch run without YAML
+## Batch run
 
-User can also batch run a flow without YAML.
-Instead of calling `pf.save` to create flow YAML first.
+User can also batch run a flow.
 
 ::::{tab-set}
 :::{tab-item} CLI
@@ -85,14 +85,13 @@ pf run create --flow "path.to.module:ClassName" --data "./data.jsonl"
 :sync: SDK
 ```python
 # user can also directly use entry in `flow` param for batch run
-pf.run(flow="path.to.module:ClassName", data="./data.jsonl")
+pf.run(flow="path.to.module:ClassName", init="./init.jsonl", data="./data.jsonl")
 ```
 
 :::
 ::::
 
 Or directly run the imported flow class or flow instance.
-**Note**: this only works in local.
 
 ```python
 class MyFlow:
@@ -103,6 +102,18 @@ flow_obj = MyFlow(model_config=config, flow_config={})
 pf.run(flow=flow_obj, data="./data.jsonl")
 ```
 
+Learn more on this topic on [Run and evaluate a flow](../run-and-evaluate-a-flow/index.md)
+
+## YAML support
+
+User can write a YAML file with name `flow.flex.yaml` manually or save a function/callable entry to YAML file.
+A flow YAML may look like this:
+
+```yaml
+$schema: https://azuremlschemas.azureedge.net/promptflow/latest/Flow.schema.json
+entry: path.to.module:ClassName
+```
+
 ## Batch run with YAML
 
 User can batch run a flow. Flow init function's param is supported by `init` parameter.
@@ -155,7 +166,7 @@ pfazure.run(flow="./flow.flex.yaml", init={"model_config": config, "flow_config"
 :::
 ::::
 
-## Serve
+## Deploy a flow
 
 User can serve a flow. Flow init function's param is supported by `init` parameter.
 The flow should have complete init/inputs/outputs specification in YAML to make sure serving swagger can be generated.
@@ -178,9 +189,7 @@ User need to write an JSON file as init's value since it's hard to write model c
 pf flow serve --source "./"  --port 8088 --host localhost --init path/to/init.json
 ```
 
-## Build & deploy
-
-Build & deploy a flow is supported: [Deploy a flow](../deploy-a-flow/index.md).
+Learn more: [Deploy a flow](../deploy-a-flow/index.md).
 
 ## Connection support
 
@@ -247,7 +256,9 @@ pf run create --flow . --data ./data.jsonl --environment-variables NEW_API_KEY='
 
 The `NEW_API_KEY`'s value won't be resolved to connection's API key.
 
-## Aggregation support (metrics)
+## Aggregation support
+
+Aggregation support is introduce to help user calculate metrics.
 
 ```python
 class MyFlow:

diff --git a/docs/how-to-guides/develop-a-flex-flow/function-based-flow.md b/docs/how-to-guides/develop-a-flex-flow/function-based-flow.md
@@ -6,8 +6,9 @@ This is an experimental feature, and may change at any time. Learn [more](../faq
 
 User can directly use a function as flow entry.
 
-## Authoring
+## Function as a flow
 
+Assume we have a file `flow_entry.py`:
 
 ```python
 from promptflow.tracing import trace
@@ -16,49 +17,46 @@ class Reply(TypedDict):
     output: str
 
 @trace
-def my_flow(text: str) -> Reply:
+def my_flow(question: str) -> Reply:
     # flow logic goes here
     pass
 ```
 
-**Note** tracing is supported for flow. Check [here](../tracing/index.md) for more information.
-
-## YAML support
-
-
-User can write a YAML file with name `flow.flex.yaml` manually or save a function/callable entry to YAML file.
-A flow YAML may look like this:
-
-```yaml
-$schema: https://azuremlschemas.azureedge.net/promptflow/latest/Flow.schema.json
-entry: path.to.module:function_name
-```
+**Note** function decorated with `@trace` will emit trace can be viewed in UI provided by PromptFlow. Check [here](../tracing/index.md) for more information.
 
 ## Flow test
 
 Since flow's definition is normal python function/callable class. We recommend user directly run it like running other scripts:
 
 ```python
 from flow_entry import my_flow
+
 if __name__ == "__main__":
-    output = my_flow(**call_args)
+    output = my_flow(question="What's the capital of France?")
     print(output)
 ```
 
-## Chat with a flow
+You can also test the flow using CLI:
+```bash
+# flow entry syntax: path.to.module:function_name
+pf flow test --flow flow_entry:myflow --inputs question="What's the capital of France?"
+```
+
+Check out a full example here: [basic](https://github.com/microsoft/promptflow/tree/main/examples/flex-flows/basic)
+
+### Chat with a flow
 
-Chat with flow in CLI:
+Start a UI to chat with a flow:
 
 ```bash
-pf flow test --flow path/to/flow --inputs path/to/inputs --ui
+pf flow test --flow flow_entry:myflow --inputs question="What's the capital of France?" --ui
 ```
 
 Check [here](../chat-with-a-flow/index.md) for more information.
 
-## Batch run without YAML
+## Batch run
 
-User can also batch run a flow without YAML.
-Instead of calling `pf.save` to create flow YAML first.
+User can also batch run a flow.
 
 ::::{tab-set}
 :::{tab-item} CLI
@@ -73,13 +71,31 @@ pf run create --flow "path.to.module:function_name" --data "./data.jsonl"
 :::{tab-item} SDK
 :sync: SDK
 ```python
+
+from path.to.module import my_flow
+pf.run(flow=my_flow, data="./data.json;")
+
 # user can also directly use entry in `flow` param for batch run
 pf.run(flow="path.to.module:function_name", data="./data.jsonl")
 ```
-
 :::
 ::::
 
+Learn more on this topic on [Run and evaluate a flow](../run-and-evaluate-a-flow/index.md)
+
+## Define a flow yaml
+
+User can write a YAML file with name `flow.flex.yaml` manually or save a function/callable entry to YAML file.
+This is required for advanced scenario like deployment or run in cloud.
+A flow YAML may look like this:
+
+```yaml
+$schema: https://azuremlschemas.azureedge.net/promptflow/latest/Flow.schema.json
+entry: path.to.module:function_name
+sample:
+  question: "what's the capital of France?"
+```
+
 ## Batch run with YAML
 
 User can batch run a flow with YAML.
@@ -89,7 +105,10 @@ User can batch run a flow with YAML.
 :sync: CLI
 
 ```bash
-pf run create --flow "./flow.flex.yaml" --data "./data.jsonl"
+# against flow file
+pf run create --flow "path/to/flow/flow.flex.yaml" --data "./data.jsonl"
+# against a folder if it has a flow.flex.yaml file
+pf run create --flow "path/to/flow" --data "./data.jsonl"
 ```
 
 :::
@@ -105,25 +124,18 @@ pf.run(flow="./flow.flex.yaml", data="./data.jsonl")
 :::
 ::::
 
-Or directly run the imported function.
-**Note**: this only works in local.
+## Deploy a flow
 
-```python
-from path.to.module import my_flow
-pf.run(flow=my_flow, data="./data.json;")
-```
-
-## Serve
-
-User can serve a flow.
+User can serve a flow as a http endpoint locally or deploy it to multiple platforms.
 
 ```bash
+# serve locally from a folder if it has a flow.flex.yaml file
+pf flow serve --source "path/to/flow/dir"  --port 8088 --host localhost
+
+# serve locally from certain file
 pf flow serve --source "./flow.flex.yaml"  --port 8088 --host localhost
 ```
-
-## Build & deploy
-
-Build & deploy a flow is supported, see [Deploy a flow](../deploy-a-flow/index.md).
+Learn more: [Deploy a flow](../deploy-a-flow/index.md).
 
 ## Next steps
 

diff --git a/docs/how-to-guides/develop-a-flex-flow/input-output-format.md b/docs/how-to-guides/develop-a-flex-flow/input-output-format.md
@@ -6,13 +6,13 @@ This is an experimental feature, and may change at any time. Learn [more](../faq
 
 ## Supported types
 
-We'll only support the following types in flow. Flow inits/inputs/outputs without specification will lead to validation error.
+Promptflow officially support below types in flow. 
 
-Inputs: primitive types(int, float, bool, str), dict, TypedDict, list
+- Inputs: primitive types(`int`, `float`, `bool`, `str`), `dict`, `TypedDict`, `list`
 
-Outputs: primitive types(int, float, bool, str), dict, TypedDict, data class, list
+- Outputs: primitive types(`int`, `float`, `bool`, `str`), `dict`, `TypedDict`, `dataclass`, `list`
 
-Init: primitive types(int, float, bool, str), connection, ModelConfiguration, TypedDict, list
+- Init: primitive types(`int`, `float`, `bool`, `str`), `Connection`, `ModelConfiguration`, `TypedDict`, `list`
 
 If user has non-supported types in code/YAML, validation error will be raised.
 
@@ -37,5 +37,7 @@ Sample validation error: "The input 'my_own_obj' is of a complex python type. Pl
 
 ## Stream
 
-Stream is supported in flow.
-Reference this [sample](https://microsoft.github.io/promptflow/tutorials/stream-flex-flow.html) for details.
+Stream is supported in flow, you just need to return a generator type in your function.
+Reference openai doc on how to do it using plain python code: [how_to_stream_completions](https://cookbook.openai.com/examples/how_to_stream_completions).
+
+Reference this flow [sample](https://microsoft.github.io/promptflow/tutorials/stream-flex-flow.html) for details.
diff --git a/docs/how-to-guides/develop-a-prompty/prompty-output-format.md b/docs/how-to-guides/develop-a-prompty/prompty-output-format.md
@@ -66,7 +66,7 @@ Prompty can return the content of the first choice as a dictionary object when t
 - The `response_format` is defined as `type: json_object` in the parameters
 - The template specifies the JSON format for the return value.
 
-**Note**: `response_format` is compatible with `GPT-4 Turbo` and all GPT-3.5 Turbo models newer than `gpt-3.5-turbo-1106`. For more details, refer to this [document](https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format).
+**Note**: `json_object` response_format is compatible with `GPT-4 Turbo` and all GPT-3.5 Turbo models newer than `gpt-3.5-turbo-1106`. For more details, refer to this [document](https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format).
 
 Here’s how to configure a prompty for JSON object output:
 ```yaml