AI integrations compatibility matrix
Questi contenuti non sono ancora disponibili nella tua lingua.
Aspire provides several AI hosting and client integrations that enable you to work with different AI services and platforms. This article is a compatibility reference showing which client integrations work with which hosting integrations, along with the recommended pairings and AppHost API examples.
Compatibility matrix
Section titled “Compatibility matrix”The following table shows the compatibility between Aspire AI hosting and client integrations:
| Hosting Integration | Aspire.OpenAI | Aspire.Azure.AI.OpenAI | Aspire.Azure.AI.Inference |
|---|---|---|---|
Aspire.Hosting.Foundry | ⚠️ Partial — Foundry Local only (preferred) | ⚠️ Partial | ❗ Legacy |
Aspire.Hosting.Azure.CognitiveServices | ❌ No | ✅ Yes (preferred) | ❌ No |
Aspire.Hosting.OpenAI | ✅ Yes (preferred) | ✅ Yes | ❌ No |
Recommended pairings
Section titled “Recommended pairings”In general, use an Aspire client integration when one supports the resource and its authentication method. Use Aspire.OpenAI for OpenAI-compatible resources that provide an API key, including Foundry Local. For cloud-provisioned Microsoft Foundry resources, use the OpenAI SDK directly because they authenticate with managed identity.
Microsoft Foundry
Section titled “Microsoft Foundry”For Foundry Local resources, use the Aspire.OpenAI client integration. It provides dependency injection and telemetry for the OpenAI-compatible endpoint and the API key that Foundry Local exposes. Cloud-provisioned Microsoft Foundry resources use managed identity, which Aspire.OpenAI does not support; use the OpenAI SDK directly for those resources.
For more information, see Microsoft Foundry integration.
Hosting integration
Section titled “Hosting integration”The Aspire.Hosting.Foundry package provides the hosting integration. In your app host project:
import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const foundry: FoundryResource
const builder: IDistributedApplicationBuilder
IDistributedApplicationBuilder.addFoundry(name: string): FoundryResource
Adds a Microsoft Foundry resource to the application model.
addFoundry("foundry").FoundryResource.runAsFoundryLocal(endpoint?: string): FoundryResource
Configures a Microsoft Foundry resource to use an Aspire-managed or existing Foundry Local service.
runAsFoundryLocal();
const const chat: FoundryDeploymentResource
const foundry: FoundryResource
FoundryResource.addDeployment(name: string, model: FoundryModel | string, options?: { modelVersion?: string; format?: string;} | undefined): FoundryDeploymentResource (+1 overload)
Adds a Microsoft Foundry deployment resource to a Microsoft Foundry resource.
addDeployment('chat', { FoundryModel.name?: string | undefined
FoundryModel.version?: string | undefined
FoundryModel.format?: string | undefined
const builder: IDistributedApplicationBuilder
IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js") .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(const chat: FoundryDeploymentResource
var builder = DistributedApplication.CreateBuilder(args);
var foundry = builder.AddFoundry("foundry") .RunAsFoundryLocal();
var chat = foundry.AddDeployment("chat", FoundryModel.Local.Phi4);
builder.AddProject<Projects.ExampleProject>() .WithReference(chat);Client integration
Section titled “Client integration”For Foundry Local, the Aspire.OpenAI package provides the recommended client integration. For its configuration sample, see Connect with Aspire.OpenAI. For cloud-provisioned Foundry resources that authenticate with managed identity, use the OpenAI SDK directly as shown on that page.
Azure Cognitive Services (Azure OpenAI)
Section titled “Azure Cognitive Services (Azure OpenAI)”For Azure OpenAI resources, use the Aspire.Azure.AI.OpenAI client integration for full Azure-specific features and authentication support. For more information, see Azure OpenAI integration.
Hosting integration
Section titled “Hosting integration”The Aspire.Hosting.Azure.CognitiveServices package provides the hosting integration. In your app host project:
import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const openai: AzureOpenAIResource
const builder: IDistributedApplicationBuilder
IDistributedApplicationBuilder.addAzureOpenAI(name: string): AzureOpenAIResource
Adds an Azure OpenAI resource to the application model.
addAzureOpenAI("openai");
await const builder: IDistributedApplicationBuilder
IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js") .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(const openai: AzureOpenAIResource
var builder = DistributedApplication.CreateBuilder(args);
var openai = builder.AddAzureOpenAI("openai");
builder.AddProject<Projects.ExampleProject>() .WithReference(openai);Client integration
Section titled “Client integration”The Aspire.Azure.AI.OpenAI package provides the client integration. In your service project:
builder.AddAzureOpenAIClient("openai");Direct OpenAI
Section titled “Direct OpenAI”For direct OpenAI API access, use the Aspire.OpenAI client integration. For more information, see Aspire OpenAI integration (Preview).
Hosting integration
Section titled “Hosting integration”The Aspire.Hosting.OpenAI package provides the hosting integration. In your app host project:
import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const openai: OpenAIResource
const builder: IDistributedApplicationBuilder
IDistributedApplicationBuilder.addOpenAI(name: string): OpenAIResource
Adds an OpenAI parent resource that can host multiple models.
addOpenAI("openai");
await const builder: IDistributedApplicationBuilder
IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp("api", "./api", "index.js") .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(const openai: OpenAIResource
var builder = DistributedApplication.CreateBuilder(args);
var openai = builder.AddOpenAI("openai");
builder.AddProject<Projects.ExampleProject>() .WithReference(openai);Client integration
Section titled “Client integration”The Aspire.OpenAI package provides the client integration. In your service project:
builder.AddOpenAIClient("openai");Connection string formats
Section titled “Connection string formats”Understanding how hosting and client integrations communicate through connection strings can help you troubleshoot connectivity issues and understand the underlying mechanics.
Each hosting integration generates connection strings in different formats that are consumed by the client integrations.
Hosting integration connection strings
Section titled “Hosting integration connection strings”Aspire.Hosting.Foundry
Section titled “Aspire.Hosting.Foundry”Azure:
Endpoint={Endpoint};EndpointAIInference={EndpointAIInference}modelsFoundry Local:
Endpoint={EmulatorServiceUri};Key={ApiKey}Deployment:
{Parent};Deployment={DeploymentName}Aspire.Hosting.Azure.CognitiveServices
Section titled “Aspire.Hosting.Azure.CognitiveServices”Deployment:
{ConnectionString};Deployment={DeploymentName}Aspire.Hosting.OpenAI
Section titled “Aspire.Hosting.OpenAI”Endpoint={Endpoint};Key={Key};Model={Model}Client integration connection string requirements
Section titled “Client integration connection string requirements”Aspire.OpenAI
Section titled “Aspire.OpenAI”Expects connection strings in the format:
Endpoint={Endpoint};Key={Key};Deployment={Deployment};Model={Model}Uses either Deployment or Model (in that order). Deployment is set by Aspire.Hosting.Azure.CognitiveServices while Model is set by Aspire.Hosting.OpenAI.
Aspire.Azure.AI.OpenAI
Section titled “Aspire.Azure.AI.OpenAI”Expects connection strings in the format:
Endpoint={Endpoint};Key={Key};Deployment={Deployment};Model={Model}Uses either Deployment or Model (in that order). Deployment is set by Aspire.Hosting.Azure.CognitiveServices while Model is set by Aspire.Hosting.OpenAI.
This integration is a superset of Aspire.OpenAI and supports TokenCredential and Azure-specific features.
Aspire.Azure.AI.Inference
Section titled “Aspire.Azure.AI.Inference”Expects connection strings in the format:
Endpoint={Endpoint};EndpointAIInference={EndpointAIInference};Key={Key};Deployment={DeploymentName};Model={ModelName}Uses either Deployment or Model (in that order).
Uses EndpointAIInference if available, otherwise Endpoint.
Aspire