Clarify Azure properties

[agoncal]

When invoking Azure OpenAI with pure LangChain4j, this is the code you need:

AzureOpenAiChatModel model = AzureOpenAiChatModel.builder()
      .apiKey(AZURE_OPENAI_KEY)
      .endpoint(AZURE_OPENAI_ENDPOINT)
      .deploymentName(AZURE_OPENAI_DEPLOYMENT_NAME)
      .temperature(0.9)
      .build();

apiKey, endpoint and deploymentName are mandatory. If you look at the Azure Console, the Deployment Name is random name you can choose and then you deploy a model (gpt-35-turbo)

At the moment, the extension had four mandatory properties instead of three:

quarkus.langchain4j.azure-openai.api-key=
quarkus.langchain4j.azure-openai.endpoint=
quarkus.langchain4j.azure-openai.deployment-id=
quarkus.langchain4j.azure-openai.resource-name=

Could we rename deployment-id with deployment-name so that it fits better with the LangChain4j API (deploymentName) and the Azure naming convention ?

And what is resource-name (I thought it would be the model name, but it does not work) and why it is mandatory ?

cc @edeandrea @geoand

[edeandrea]

I don't see quarkus.langchain4j.azure-openai.endpoint as a property? That property isn't there in https://github.com/quarkiverse/quarkus-langchain4j/blob/main/openai/azure-openai/runtime/src/main/java/io/quarkiverse/langchain4j/azure/openai/runtime/config/Langchain4jAzureOpenAiConfig.java

[edeandrea]

base url is computed from resource name & deployment id

https://${quarkus.langchain4j.azure-openai.resource-name}.openai.azure.com/openai/deployments/${quarkus.langchain4j.azure-openai.deployment-id}

[edeandrea]

we could certainly rename baseUrl to endpoint if that would make things more clear, but at the end of the day having to know the fully-qualified url of where the service is isn't really required. Just knowing the Azure Cognitive service name and the deployment id is enough.

I also agree that deployment name would be better and more consistent.

[edeandrea]

Maybe the correct logic should be this...

If resource-name and deployment-name (renamed from deployment-id) are set, then automatically construct the endpoint url.

If endpoint (we rename baseUrl to endpoint) is set, then use it, and resource-name and deployment-id are NOT required (because they are never read).

@agoncal / @geoand thoughts?

[geoand]

I'll defer to you guys since you know a lot more about Azure than I do

[edeandrea]

After some investigation it seems that maybe the nomenclature in Langchain4j is a little misleading.

deploymentName in Langchain4j refers to the model name in the model class and has nothing to do with the name of the model deployed on Azure

Even in the Microsoft docs it refers to the Azure OpenAI deployment as deployment-id. See https://learn.microsoft.com/en-us/azure/ai-services/openai/reference

I have no issues with being more flexible, so this is what I propose:

• If endpoint (re-named from base-url) is set, use it. Disregard resource-name and deployment-id.
• If resource-name and deployment-id are set, then automatically construct the endpoint url. If either of these 2 properties are missing, and endpoint is missing, then its an error condition

[geoand]

I like that plan

[edeandrea]

I guess I'll take it upon myself to implement this :D

[geoand]

💪🏼

[edeandrea]

Maybe this afternoon.

[geoand]

I can wait until next week :)

[edeandrea]

The beauty of being -7 hours from you :)

[edeandrea]

So...re-naming something is most definitely a breaking change. Are we ok making a breaking change like that? Or should we deprecate the existing one and introduce a new one?

[agoncal]

Well, it's up to all of you, but looking at the rapid pace where everything is evolving and that all the libraries are in 0.x.something... I would just break things.

[geoand]

So...re-naming something is most definitely a breaking change. Are we ok making a breaking change like that? Or should we deprecate the existing one and introduce a new one?

Yeah, it's fine to break

[edeandrea]

That's what I thought as well, but just wanted to confirm.

[sarxos]

Hi :) Just my few cents.

I've started playing with this extension a few days ago, so this is the feedback from the first-time extension user :D

When I was integrating it in my prototype I had some serious thoughts when searching for deployment-id and didn't find it in the Azure. I decided to go with the deployment name, but that was my pure guess, and it just started to work. Good for me. But please believe me, if it didn't run and I would need to investigate, the first thing I would assume is that the deployment name is not an ID and I provided it with a wrong value.

Even in the Microsoft docs it refers to the Azure OpenAI deployment as deployment-id. See https://learn.microsoft.com/en-us/azure/ai-services/openai/reference

They (Microsoft) are very inconclusive in this regard. They sometimes use the "name" phrase and sometimes they use "id".

But I believe that renaming the configuration property from deployment-id to deployment-name would be the best because when you look at it in the Azure OpenAI Studio (this is the place where users configure their deployments) it's called exactly like that.

[geoand]

Thanks for the feedback @sarxos.

@radcortez does @ConfigMapping have any kind of alias support?

[agoncal]

Yes @sarxos Azure can be confusing. But I agree, deployment-name is what's used in Azure CLI and Azure Console. I've also discovered the word deployment-id with this extension.

[geoand]

Thanks @agoncal.

So if we can't get an automatic alias, we probably want to straight up rename the property @edeandrea

[edeandrea]

I can do that rename as well as endpoint as part of this pr.

[geoand]

🙏

[edeandrea]

Thank you for your comments @sarxos . #249 will address this, as well as some other things.

[radcortez]

@radcortez does @ConfigMapping have any kind of alias support?

Not directly, we are considering one in: smallrye/smallrye-config#1077

It is possible to create a relocate / fallback for the property alone (or other properties that require it):
https://smallrye.io/smallrye-config/3.5.2/extensions/relocate/
https://smallrye.io/smallrye-config/3.5.2/extensions/fallback/

[geoand]

Thanks @radcortez