[FLINK-37799][model][docs] Add document for OpenAI Model Function #26671

yunfengzhou-hub · 2025-06-12T07:05:43Z

What is the purpose of the change

This PR is a continuation to #26652, adding document for the introduced OpenAI Model Function.

Brief change log

Adds document for the OpenAI Model Function.

Verifying this change

This change is a trivial rework / code cleanup without any test coverage.

Does this pull request potentially affect one of the following parts:

Dependencies (does it add or upgrade a dependency): no
The public API, i.e., is any changed class annotated with @Public(Evolving): no
The serializers: no
The runtime per-record code paths (performance sensitive): no
Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: no
The S3 file system connector: no

Documentation

Does this pull request introduce a new feature? yes
If yes, how is the feature documented? docs

flinkbot · 2025-06-12T07:08:59Z

CI report:

18640aa Azure: SUCCESS

Bot commands

The @flinkbot bot supports the following commands:

@flinkbot run azure re-run the last Azure build

davidradl · 2025-06-13T10:58:59Z

docs/content/docs/connectors/models/openai.md

+
+# OpenAI
+
+The OpenAI Model Function allows Flink SQL to call OpenAI API for inference tasks.


I suggest a link to the OpenAI javadoc on the words OpenAI API

Thanks for the comment! I've add the link.

yunfengzhou-hub · 2025-06-18T06:11:25Z

Hi @fsk119 @lihaosky could you please help review this PR?

davidradl · 2025-06-18T12:18:57Z

docs/content/docs/connectors/models/openai.md

+
+The function supports calling remote OpenAI model services via Flink SQL for prediction/inference tasks. Currently, the following tasks are supported:
+
+* chat completions


I think there needs to be more information about these 2 tasks, and why we are restricted to these tasks?
It would be good to include links to what these mean,
https://platform.openai.com/docs/api-reference/chat
https://platform.openai.com/docs/api-reference/embeddings

Thanks for the comment. I've added a link and a brief description to each of the 2 tasks.

why we are restricted to these tasks?

Because more tasks require additional Model Function subclasses to adapt, which has not been implemented yet. Despite that the other tasks are not supported, the current 2 tasks should have been enough for examples and demos proving the end-to-end functionality of Flink Model Functions in this early phase. We can continue to add support for more tasks in future.

Given that the above message is pure developer's consideration, I would prefer not to expose such reasons to readers of this document.

davidradl · 2025-06-18T12:24:52Z

docs/content/docs/connectors/models/openai.md

+
+## Usage examples
+
+The following example creates a chat completions model and use it to predict sentiment labels for movie reviews.


nit: use -> uses

davidradl · 2025-06-18T12:27:06Z

docs/content/docs/connectors/models/openai.md

+WITH (
+    'provider'='openai',
+    'endpoint'='https://api.openai.com/v1/chat/completions',
+    'api-key' = '<YOUR KEY>',


I suggest we define <YOUR KEY>.

I'm not sure about what it means to "define" <YOUR KEY>. Do you mean we should somehow define a variable or constant in this markdown document?

davidradl · 2025-06-18T12:28:55Z

docs/content/docs/connectors/models/openai.md

+            <td>required</td>
+            <td style="word-wrap: break-word;">(none)</td>
+            <td>String</td>
+            <td>Full URL of the OpenAI API endpoint, e.g., <code>https://api.openai.com/v1/chat/completions</code> or


nit: e.g., -> e.g.

davidradl · 2025-06-18T12:36:10Z

docs/content/docs/connectors/models/openai.md

+    </tbody>
+</table>
+
+### chat/completions


chat/completions is different to chat completions that we mentioned earlier as a task. I suggest being consistent.

davidradl · 2025-06-18T12:41:22Z

docs/content/docs/connectors/models/openai.md

+            <td>optional</td>
+            <td style="word-wrap: break-word;">"You are a helpful assistant."</td>
+            <td>String</td>
+            <td>System message for chat tasks.</td>


It would be useful to point into the OpenAI docs as to what this and the other parameters mean. I notice we use the phrase system-prompt an System message, I suggest we define one and point to it an only use one way to refer to this. When we say system here - do we mean system role?

Thanks for the comment. system-prompt means the context message for the system role in the input request for OpenAI API. I have changed its description to clarify this ambiguity.

I suggest we define one and point to it an only use one way to refer to this.

Same as the comment above, I'm not sure how to "define one". Is it something like a variable or constant?

fsk119

Thanks for your contribution.

fsk119 · 2025-06-20T02:54:21Z

docs/content/docs/connectors/models/openai.md

+            <td>optional</td>
+            <td style="word-wrap: break-word;">null</td>
+            <td>Double</td>
+            <td>Probability cutoff for token selection (used instead of temperature). See <a href=\"https://platform.openai.com/docs/api-reference/responses/create#responses-create-top_p\">top_p</a></td>


Seems the current link doesn't work. You can take a look at this.

https://github.com/apache/flink-connector-kafka/blob/main/docs/content/docs/connectors/table/kafka.md?plain=1#L236C130-L236C183

lihaosky · 2025-06-20T04:50:33Z

docs/content/docs/connectors/models/openai.md

+<table class="table table-bordered">
+    <thead>
+        <tr>
+            <th class="text-center">Task Type</th>


What's this task type?

It corresponds to the tasks mentioned in the document above.

The function supports calling remote OpenAI model services via Flink SQL for prediction/inference tasks. Currently, the following tasks are supported...

There is no model option named task type yet. I have changed this line from "Task Type" to "Task" to avoid possible ambiguity.

fsk119

LGTM

lihaosky

LGTM! Thanks

[FLINK-37799][model][docs] Add document for OpenAI Model Function

533799b

yunfengzhou-hub marked this pull request as ready for review June 12, 2025 07:06

yunfengzhou-hub mentioned this pull request Jun 12, 2025

[FLINK-37799][model] Support OpenAI Model Function #26652

Merged

davidradl reviewed Jun 13, 2025

View reviewed changes

yunfengzhou-hub added 2 commits June 16, 2025 08:51

Add link to OpenAI document

0f76b7c

Fix trailing whitespace and \t

2c49cc6

davidradl reviewed Jun 18, 2025

View reviewed changes

Update naming and links according to PR comment

011fb69

fsk119 reviewed Jun 20, 2025

View reviewed changes

lihaosky reviewed Jun 20, 2025

View reviewed changes

Fix links and task type

18640aa

fsk119 approved these changes Jun 21, 2025

View reviewed changes

lihaosky approved these changes Jun 21, 2025

View reviewed changes

fsk119 merged commit ceecdb7 into apache:master Jun 21, 2025


		# OpenAI

		The OpenAI Model Function allows Flink SQL to call OpenAI API for inference tasks.


		The function supports calling remote OpenAI model services via Flink SQL for prediction/inference tasks. Currently, the following tasks are supported:

		* chat completions


		## Usage examples

		The following example creates a chat completions model and use it to predict sentiment labels for movie reviews.

[FLINK-37799][model][docs] Add document for OpenAI Model Function #26671

[FLINK-37799][model][docs] Add document for OpenAI Model Function #26671

Uh oh!

Conversation

yunfengzhou-hub commented Jun 12, 2025

What is the purpose of the change

Brief change log

Verifying this change

Does this pull request potentially affect one of the following parts:

Documentation

Uh oh!

flinkbot commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI report:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yunfengzhou-hub commented Jun 18, 2025

Uh oh!

davidradl Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidradl Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidradl Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fsk119 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fsk119 left a comment

Choose a reason for hiding this comment

Uh oh!

lihaosky left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

flinkbot commented Jun 12, 2025 •

edited

Loading

davidradl Jun 18, 2025 •

edited

Loading

davidradl Jun 18, 2025 •

edited

Loading

davidradl Jun 18, 2025 •

edited

Loading