diff --git a/providers/openai/docs/index.rst b/providers/openai/docs/index.rst index 7b2d212ea53ce..56ffcf67b0ba9 100644 --- a/providers/openai/docs/index.rst +++ b/providers/openai/docs/index.rst @@ -34,6 +34,7 @@ :maxdepth: 1 :caption: Guides + Quick start Connection types Operators diff --git a/providers/openai/docs/quickstart.rst b/providers/openai/docs/quickstart.rst new file mode 100644 index 0000000000000..417645a930dab --- /dev/null +++ b/providers/openai/docs/quickstart.rst @@ -0,0 +1,75 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/quickstart: + +Quick start +=========== + +Go from zero to a generated model response in three steps: install the +provider, configure a connection, and write a Dag. + +1. Install +---------- + +.. code-block:: bash + + pip install apache-airflow-providers-openai + +2. Configure the connection +---------------------------- + +Every call goes through an OpenAI connection (``conn_type`` ``openai``, +default connection id ``openai_default``). Specify your OpenAI API key in +the password field. See :ref:`howto/connection:openai` for the full +reference, including workload identity authentication (Kubernetes, Azure, +GCP, or a custom token provider) if you'd rather exchange short-lived +identity tokens than store a long-lived API key. + +The quickest way to set one up is an environment variable: + +.. code-block:: bash + + export AIRFLOW_CONN_OPENAI_DEFAULT='{"conn_type": "openai", "password": "sk-..."}' + +Or add it through the Airflow UI (``Admin > Connections``) or the CLI (``airflow connections add``). + +3. Write your first Dag +------------------------ + +The :class:`~airflow.providers.openai.operators.openai.OpenAIResponseOperator` +generates a model response with the OpenAI Responses API and returns the +response's aggregated output text: + + +.. exampleinclude:: /../../openai/src/airflow/providers/openai/example_dags/example_response.py + :language: python + :start-after: [START quickstart_response] + :end-before: [END quickstart_response] + +Run it like any other Dag (``airflow dags test quickstart_openai``) and the +``generate_response`` task pushes the aggregated output text to XCom. + +Where to go next +----------------- + +- :doc:`operators/openai` — the full operator set: embeddings with + ``OpenAIEmbeddingOperator``, batch jobs with ``OpenAITriggerBatchOperator``, + and the Responses/Conversations ``OpenAIHook`` methods for use inside + ``@task`` functions. +- :ref:`howto/connection:openai` — the full connection reference, including + workload identity authentication. diff --git a/providers/openai/src/airflow/providers/openai/example_dags/__init__.py b/providers/openai/src/airflow/providers/openai/example_dags/__init__.py new file mode 100644 index 0000000000000..13a83393a9124 --- /dev/null +++ b/providers/openai/src/airflow/providers/openai/example_dags/__init__.py @@ -0,0 +1,16 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. diff --git a/providers/openai/src/airflow/providers/openai/example_dags/example_response.py b/providers/openai/src/airflow/providers/openai/example_dags/example_response.py new file mode 100644 index 0000000000000..1faffca8d0e62 --- /dev/null +++ b/providers/openai/src/airflow/providers/openai/example_dags/example_response.py @@ -0,0 +1,36 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +# [START quickstart_response] +from __future__ import annotations + +# This is for Airflow 2.11. For Airflow 3+, use `from airflow.sdk import dag` +from airflow.providers.common.compat.sdk import dag +from airflow.providers.openai.operators.openai import OpenAIResponseOperator + + +@dag(tags=["example"]) +def quickstart_openai(): + OpenAIResponseOperator( + task_id="generate_response", + conn_id="openai_default", + input_text="Write a one-sentence summary of Apache Airflow.", + ) + + +quickstart_openai() +# [END quickstart_response]