update

Author: cloga

articles/ai-studio/how-to/create-manage-runtime.md

@@ -99,6 +99,7 @@ Automatic is the default option for a runtime. You can start an automatic runtim
 On a flow page, you can use the following options to manage an automatic runtime:
 
 - **Install packages** triggers `pip install -r requirements.txt` in the flow folder. The process can take a few minutes, depending on the packages that you install.
+- **View installed packages** shows the packages that are installed in the runtime. It includes the packages baked to base image and packages specify in the `requirements.txt` file in the flow folder.
 - **Reset** deletes the current runtime and creates a new one with the same environment. If you encounter a package conflict, you can try this option.
 - **Edit** opens the runtime configuration page, where you can define the VM side and the idle time for the runtime.
 - **Stop** deletes the current runtime. If there's no active runtime on the underlying compute, the compute resource is also deleted.
@@ -139,6 +140,18 @@ If you want to use a private feed in Azure DevOps, follow these steps:
 
     :::image type="content" source="../media/prompt-flow/how-to-create-manage-runtime/runtime-advanced-setting-msi.png" alt-text="Screenshot that shows the toggle for using a workspace user-assigned managed identity." lightbox = "../media/prompt-flow/how-to-create-manage-runtime/runtime-advanced-setting-msi.png":::
 
+#### Change the base image for automatic runtime (preview)
+
+By default, we use the latest prompt flow image as the base image. If you want to use a different base image, you need build your own base image, this docker image should be built from prompt flow base image that is `mcr.microsoft.com/azureml/promptflow/promptflow-runtime-stable:<newest_version>`. If possible use the [latest version of the base image](https://mcr.microsoft.com/v2/azureml/promptflow/promptflow-runtime-stable/tags/list). To use the new base image, you need to reset the runtime via the `reset` command. This process takes several minutes as it pulls the new base image and reinstalls packages.
+
+:::image type="content" source="../media/prompt-flow/how-to-create-manage-runtime/runtime-creation-automatic-image-flow-dag.png" alt-text="Screenshot of actions for customizing an base image for an automatic runtime on a flow page." lightbox = "../media/prompt-flow/how-to-create-manage-runtime/runtime-creation-automatic-image-flow-dag.png":::
+
+```yaml
+environment:
+    image: <your-custom-image>
+    python_requirements_txt: requirements.txt
+```
+
 ### Update a compute instance runtime on a runtime page
 
 Azure AI Studio gets regular updates to the base image (`mcr.microsoft.com/azureml/promptflow/promptflow-runtime-stable`) to include the latest features and bug fixes. To get the best experience and performance, periodically update your runtime to the [latest version](https://mcr.microsoft.com/v2/azureml/promptflow/promptflow-runtime-stable/tags/list).

articles/ai-studio/media/prompt-flow/how-to-create-manage-runtime/runtime-create-automatic-actions.png

@@ -112,7 +112,7 @@ Before you create a compute instance runtime, make sure that a compute instance
 
      :::image type="content" source="./media/how-to-create-manage-runtime/runtime-creation-ci-existing-custom-application-ui.png" alt-text="Screenshot of the option to use an existing custom application and the box for selecting an application." lightbox = "./media/how-to-create-manage-runtime/runtime-creation-ci-existing-custom-application-ui.png":::
 
-## Use a runtime in prompt flow authoring
+## Use a runtime in prompt flow authoring UI
 
 When you're authoring a flow, you can select and change the runtime from the **Runtime** dropdown list on the upper right of the flow page.
 
@@ -122,13 +122,97 @@ When you're performing evaluation, you can use the original runtime in the flow
 
 :::image type="content" source="./media/how-to-create-manage-runtime/runtime-authoring-bulktest.png" alt-text="Screenshot of runtime details on the wizard page for configuring an evaluation." lightbox = "./media/how-to-create-manage-runtime/runtime-authoring-bulktest.png":::
 
+## Use a runtime to submit a flow run in CLI/SDK
+
+Same as authoring UI, you can also specify the runtime in CLI/SDK when you submit a flow run.
+
+# [Azure CLI](#tab/cli)
+
+In you `run.yml` you can specify the runtime name or use the automatic runtime. If you specify the runtime name, it will use the runtime with the name you specified. If you specify automatic, it will use the automatic runtime. If you don't specify the runtime, it will use the automatic runtime by default.
+
+In automatic runtime case, you can also specify the instance type, if you don't specify the instance type,  Azure Machine Learning chooses an instance type (VM size) based on factors like quota, cost, performance and disk size, learn more about [serverless compute](../how-to-use-serverless-compute.md)
+
+```yaml
+$schema: https://azuremlschemas.azureedge.net/promptflow/latest/Run.schema.json
+flow: <path_to_flow>
+data: <path_to_flow>/data.jsonl
+
+column_mapping:
+  url: ${data.url}
+
+# define cloud resource
+# if omitted, it will use the automatic runtime, you can also specify the runtime name, specify automatic will also use the automatic runtime.
+# runtime: <runtime_name> 
+
+
+# define instance type only work for automatic runtime, will be ignored if you specify the runtime name.
+resources:
+  instance_type: <instance_type>
+
+```
+
+Submit this run via CLI:
+
+```sh
+pfazure run create --file run.yml
+```
+
+# [Python SDK](#tab/python)
+
+```python
+# load flow
+flow = "<path_to_flow>"
+data = "<path_to_flow>/data.jsonl"
+
+
+# define cloud resource
+# runtime = <runtime_name>
+define instance type
+resources = {"instance_type": <instance_type>}
+
+# create run
+base_run = pf.run(
+    flow=flow,
+    data=data,
+    runtime=runtime, # if omitted, it will use the automatic runtime, you can also specify the runtime name, specif automatic will also use the automatic runtime.
+#    resources = resources, # only work for automatic runtime, will be ignored if you specify the runtime name.
+    column_mapping={
+        "url": "${data.url}"
+    }, 
+)
+print(base_run)
+```
+
+Learn full e2e code first example: [Integrate prompt flow with LLM-based application DevOps](./how-to-integrate-with-llm-app-devops.md)
+
+### Referencing files outside of the flow folder - automatic runtime only
+Sometimes, you may want to reference a `requirements.txt` file that is outside of the flow folder. For example, you may want have big project which include multiple flows, and they share the same `requirements.txt` file. To do this, You can add this field `additional_includes` into the `flow.dag.yaml`. The value of this field is a list of the relative file/folder path to the flow folder. For example, if requirements.txt is in the parent folder of the flow folder, you can add `../requirements.txt` to the `additional_includes` field.
+
+```yaml
+inputs:
+  question:
+    type: string
+outputs:
+  output:
+    type: string
+    reference: ${answer_the_question_with_context.output}
+environment:
+  python_requirements_txt: requirements.txt
+additional_includes:
+  - ../requirements.txt
+...
+```
+
+When you submit flow run using automatic runtime, the `requirements.txt` file will be copied to the flow folder, and use it to start your automatic runtime.
+
 ## Update a runtime on the UI
 
 ### Update an automatic runtime (preview) on a flow page
 
 On a flow page, you can use the following options to manage an automatic runtime (preview):
 
 - **Install packages** triggers `pip install -r requirements.txt` in the flow folder. This process can take a few minutes, depending on the packages that you install.
+- **View installed packages** shows the packages that are installed in the runtime. It includes the packages baked to base image and packages specify in the `requirements.txt` file in the flow folder.
 - **Reset** deletes the current runtime and creates a new one with the same environment. If you encounter a package conflict issue, you can try this option.
 - **Edit** opens the runtime configuration page, where you can define the VM side and the idle time for the runtime.
 - **Stop** deletes the current runtime. If there's no active runtime on the underlying compute, the compute resource is also deleted.

articles/ai-studio/media/prompt-flow/how-to-create-manage-runtime/runtime-creation-automatic-image-flow-dag.png

@@ -144,9 +144,9 @@ Check if this compute instance is assigned to you and you have access to the wor
 
 This error occurs because you're cloning a flow from others that's using a compute instance as the runtime. Because the compute instance runtime is user isolated, you need to create your own compute instance runtime or select a managed online deployment/endpoint runtime, which can be shared with others.
 
-### Find Python packages installed in runtime
+### Find Python packages installed in compute instance runtime
 
-Follow these steps to find Python packages installed in runtime:
+Follow these steps to find Python packages installed in compute instance runtime:
 
 - Add a Python node in your flow.
 - Put the following code in the code section: