kaxil commented on code in PR #72049:
URL: https://github.com/apache/airflow/pull/72049#discussion_r3960694849
##########
providers/openai/docs/operators/openai.rst:
##########
@@ -58,6 +58,47 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``response_kwargs`` passes straight through to the underlying
``create_response`` call, so any
+keyword argument the Responses API accepts can be set there. Options worth
knowing about:
+
+- ``background``: run the response asynchronously on OpenAI's side. See the
note below before
+ using this with ``OpenAIResponseOperator``.
+- ``store``: whether the response is retained on OpenAI's side, for example so
it can later be
+ used as a ``previous_response_id``.
+- ``reasoning``: reasoning configuration for reasoning models.
+- ``service_tier``: one of ``'auto'``, ``'default'``, ``'flex'``, ``'scale'``
or ``'priority'``,
Review Comment:
This pins the `service_tier` values, which will go stale the next time
OpenAI adds a tier. The operator docstring links
https://platform.openai.com/docs/api-reference/responses/create but this guide
doesn't, so adding it to the intro of this section would give readers the
authoritative list.
##########
providers/openai/docs/operators/openai.rst:
##########
@@ -58,6 +58,47 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``response_kwargs`` passes straight through to the underlying
``create_response`` call, so any
+keyword argument the Responses API accepts can be set there. Options worth
knowing about:
+
+- ``background``: run the response asynchronously on OpenAI's side. See the
note below before
+ using this with ``OpenAIResponseOperator``.
+- ``store``: whether the response is retained on OpenAI's side, for example so
it can later be
+ used as a ``previous_response_id``.
+- ``reasoning``: reasoning configuration for reasoning models.
+- ``service_tier``: one of ``'auto'``, ``'default'``, ``'flex'``, ``'scale'``
or ``'priority'``,
+ selecting the processing tier the request is served from.
+- ``prompt_cache_key``: an identifier used to route requests to the same
prompt cache.
+- ``safety_identifier``: a stable identifier for the end user, used for safety
and abuse
+ detection.
+- ``truncation``: one of ``'auto'`` or ``'disabled'``, controlling whether the
model truncates
+ context that exceeds its window.
+- ``include``: additional output fields to include in the response, such as
encrypted reasoning
+ content.
+- ``metadata``: a mapping of key-value pairs attached to the response for your
own bookkeeping.
+- ``max_output_tokens``: an upper bound on the number of tokens the model can
generate.
+- ``max_tool_calls``: an upper bound on the number of built-in tool calls the
model can make.
+
+.. note::
+
+ OpenAI does not expose a spend or cost ceiling parameter on the Responses
API.
+ ``max_output_tokens`` and ``max_tool_calls`` are token and call-count
limits, not a way to cap
+ the dollar cost of a run; controlling spend means bounding those counts
yourself.
+
+.. note::
+
+ ``background=True`` starts the response running asynchronously on OpenAI's
side and returns
+ before the response finishes. ``OpenAIResponseOperator`` is synchronous:
it makes one
+ ``create_response`` call and returns ``response.output_text`` immediately,
so a response
+ started with ``background=True`` comes back incomplete, and the operator
logs its own warning
+ because ``response.status`` is not yet ``"completed"``. Use
``background=True`` only when you
Review Comment:
The "poll for completion or cancel" path isn't reachable from the operator:
`execute` returns `response.output_text` and `response.id` only goes to the
log, so nobody downstream gets the id to pass to `get_response` or
`cancel_response`. Reads clearer as a flat "don't set `background=True` on this
operator, use `OpenAIHook.create_response` from a `@task` if you need
background responses".
##########
providers/openai/docs/operators/openai.rst:
##########
@@ -58,6 +58,47 @@ specify the OpenAI connection to use, and
``response_kwargs`` to pass through op
:start-after: [START howto_operator_openai_response]
:end-before: [END howto_operator_openai_response]
+Passing Responses API options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``response_kwargs`` passes straight through to the underlying
``create_response`` call, so any
+keyword argument the Responses API accepts can be set there. Options worth
knowing about:
Review Comment:
"any keyword argument the Responses API accepts" is a bit wider than what
actually works here. `stream=True` makes `responses.create` return a
`Stream[ResponseStreamEvent]`, which has no `.status` and no `.output_text`, so
`execute` raises `AttributeError` on the very next line (checked against openai
2.37.0, the floor in this provider's pyproject). Worth narrowing the sentence,
or naming `stream` next to the `background` note below.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
