getting-started.md

SDK Core: Getting started

简体中文 | English

Add the Java dependency

dependencies {
    compileOnly "run.halo.aifoundation:api:1.0.0"
    testImplementation "run.halo.aifoundation:api:1.0.0"
}

Version 1.0.0 is available from Maven Central. For an unreleased snapshot, add the Central Snapshots repository and use the version declared in the repository's gradle.properties. Keep the API as compileOnly: AI Foundation provides these classes at runtime, and packaging a second copy can create incompatible classes across Halo plugin classloaders.

Declare the runtime plugin dependency:

spec:
    pluginDependencies:
        ai-foundation: ">=1.0.0 & <2.0.0"

Resolve AiModelService

Halo plugins have isolated Spring application contexts. Resolve the extension point instead of autowiring another plugin's service:

@Service
@RequiredArgsConstructor
public class ArticleAiService {
    private final ExtensionGetter extensionGetter;

    private Mono<AiModelService> aiModelService() {
        return extensionGetter.getEnabledExtension(AiModelService.class);
    }
}

Generate text with the configured default language model:

public Mono<String> summarize(String text) {
    return aiModelService()
        .flatMap(AiModelService::languageModel)
        .flatMap(model -> model.generateText("Summarize in one sentence:\n" + text))
        .map(GenerateTextResult::getText);
}

Resolve a named model with service.languageModel(modelName). Passing null or blank selects the default. The same pattern applies to embeddingModel, rerankingModel, and imageGenerationModel.

Resolution fails clearly when the default slot is empty, a model is missing or disabled, or its type does not match. Convert these errors into an actionable administrator-facing message.

Next: generating text or the complete plugin example.