Skip to content

Commit 1beff75

Browse files
ricken07ricken07
authored
add mistral ai moderation doc (#3161)
1 parent 55ac780 commit 1beff75

File tree

2 files changed

+192
-0
lines changed

2 files changed

+192
-0
lines changed

‎spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@
6464
**** xref:api/audio/speech/openai-speech.adoc[OpenAI]
6565
** xref:api/moderation[Moderation Models]
6666
*** xref:api/moderation/openai-moderation.adoc[OpenAI]
67+
*** xref:api/moderation/mistral-ai-moderation.adoc[Mistral AI]
6768
// ** xref:api/generic-model.adoc[]
6869
6970
* xref:api/vectordbs.adoc[]

‎spring-ai-docs/src/main/antora/modules/ROOT/pages/api/moderation/mistral-ai-moderation.adoc

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
= Moderation
2+
3+
== Introduction
4+
5+
Spring AI supports the new moderation service introduced by Mistral AI and powered by the Mistral Moderation model.
6+
It enables the detection of harmful text content along several policy dimensions.
7+
Follow this https://docs.mistral.ai/capabilities/guardrailing/[link] for more information on the Mistral AI moderation model.
8+
9+
== Prerequisites
10+
11+
. Create an Mistral AI account and obtain an API key. You can sign up at https://auth.mistral.ai/ui/registration[Mistral AI registration page] and generate an API key on the https://console.mistral.ai/api-keys/[API Keys page].
12+
. Add the `spring-ai-mistral-ai` dependency to your project's build file. For more information, refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section.
13+
14+
15+
== Auto-configuration
16+
17+
[NOTE]
18+
====
19+
There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names.
20+
Please refer to the https://docs.spring.io/spring-ai/reference/upgrade-notes.html[upgrade notes] for more information.
21+
====
22+
23+
Spring AI provides Spring Boot auto-configuration for the Mistral AI Moderation Model.
24+
To enable it add the following dependency to your project's Maven `pom.xml` file:
25+
26+
[source,xml]
27+
----
28+
<dependency>
29+
<groupId>org.springframework.ai</groupId>
30+
<artifactId>spring-ai-starter-model-mistral-ai</artifactId>
31+
</dependency>
32+
----
33+
34+
or to your Gradle `build.gradle` build file:
35+
36+
[source,groovy]
37+
----
38+
dependencies {
39+
implementation 'org.springframework.ai:spring-ai-starter-model-mistral-ai'
40+
}
41+
----
42+
43+
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
44+
45+
== Moderation Properties
46+
47+
=== Connection Properties
48+
The prefix spring.ai.mistralai is used as the property prefix that lets you connect to Mistral AI.
49+
[cols="3,3,1"]
50+
|====
51+
| Property | Description | Default
52+
| spring.ai.mistralai.base-url | The URL to connect to | https://api.mistral.ai
53+
| spring.ai.mistralai.api-key | The API Key | -
54+
|====
55+
56+
=== Configuration Properties
57+
58+
[NOTE]
59+
====
60+
Enabling and disabling of the moderation auto-configurations are now configured via top level properties with the prefix `spring.ai.model.moderation`.
61+
62+
To enable, spring.ai.model.moderation=mistral (It is enabled by default)
63+
64+
To disable, spring.ai.model.moderation=none (or any value which doesn't match mistral)
65+
66+
This change is done to allow configuration of multiple models.
67+
====
68+
69+
The prefix spring.ai.mistralai.moderation is used as the property prefix for configuring the Mistral AI moderation model.
70+
[cols="3,5,1"]
71+
|====
72+
| Property | Description | Default
73+
| spring.ai.model.moderation | Enable Moderation model | mistral
74+
| spring.ai.mistralai.moderation.base-url | The URL to connect to | https://api.mistral.ai
75+
| spring.ai.mistralai.moderation.api-key | The API Key | -
76+
| spring.ai.mistralai.moderation.options.model | ID of the model to use for moderation. | mistral-moderation-latest
77+
|====
78+
79+
NOTE: You can override the common `spring.ai.mistralai.base-url`, `spring.ai.mistralai.api-key`, properties.
80+
The `spring.ai.mistralai.moderation.base-url`, `spring.ai.mistralai.moderation.api-key`, properties, if set, take precedence over the common properties.
81+
This is useful if you want to use different Mistral AI accounts for different models and different model endpoints.
82+
83+
TIP: All properties prefixed with `spring.ai.mistralai.moderation.options` can be overridden at runtime.
84+
85+
== Runtime Options
86+
The MistralAiModerationOptions class provides the options to use when making a moderation request.
87+
On start-up, the options specified by spring.ai.mistralai.moderation are used, but you can override these at runtime.
88+
89+
For example:
90+
91+
[source,java]
92+
----
93+
MistralAiModerationOptions moderationOptions = MistralAiModerationOptions.builder()
94+
.model("mistral-moderation-latest")
95+
.build();
96+
97+
ModerationPrompt moderationPrompt = new ModerationPrompt("Text to be moderated", this.moderationOptions);
98+
ModerationResponse response = mistralAiModerationModel.call(this.moderationPrompt);
99+
100+
// Access the moderation results
101+
Moderation moderation = moderationResponse.getResult().getOutput();
102+
103+
// Print general information
104+
System.out.println("Moderation ID: " + moderation.getId());
105+
System.out.println("Model used: " + moderation.getModel());
106+
107+
// Access the moderation results (there's usually only one, but it's a list)
108+
for (ModerationResult result : moderation.getResults()) {
109+
System.out.println("\nModeration Result:");
110+
System.out.println("Flagged: " + result.isFlagged());
111+
112+
// Access categories
113+
Categories categories = this.result.getCategories();
114+
System.out.println("\nCategories:");
115+
System.out.println("Law: " + categories.isLaw());
116+
System.out.println("Financial: " + categories.isFinancial());
117+
System.out.println("PII: " + categories.isPii());
118+
System.out.println("Sexual: " + categories.isSexual());
119+
System.out.println("Hate: " + categories.isHate());
120+
System.out.println("Harassment: " + categories.isHarassment());
121+
System.out.println("Self-Harm: " + categories.isSelfHarm());
122+
System.out.println("Sexual/Minors: " + categories.isSexualMinors());
123+
System.out.println("Hate/Threatening: " + categories.isHateThreatening());
124+
System.out.println("Violence/Graphic: " + categories.isViolenceGraphic());
125+
System.out.println("Self-Harm/Intent: " + categories.isSelfHarmIntent());
126+
System.out.println("Self-Harm/Instructions: " + categories.isSelfHarmInstructions());
127+
System.out.println("Harassment/Threatening: " + categories.isHarassmentThreatening());
128+
System.out.println("Violence: " + categories.isViolence());
129+
130+
// Access category scores
131+
CategoryScores scores = this.result.getCategoryScores();
132+
System.out.println("\nCategory Scores:");
133+
System.out.println("Law: " + scores.getLaw());
134+
System.out.println("Financial: " + scores.getFinancial());
135+
System.out.println("PII: " + scores.getPii());
136+
System.out.println("Sexual: " + scores.getSexual());
137+
System.out.println("Hate: " + scores.getHate());
138+
System.out.println("Harassment: " + scores.getHarassment());
139+
System.out.println("Self-Harm: " + scores.getSelfHarm());
140+
System.out.println("Sexual/Minors: " + scores.getSexualMinors());
141+
System.out.println("Hate/Threatening: " + scores.getHateThreatening());
142+
System.out.println("Violence/Graphic: " + scores.getViolenceGraphic());
143+
System.out.println("Self-Harm/Intent: " + scores.getSelfHarmIntent());
144+
System.out.println("Self-Harm/Instructions: " + scores.getSelfHarmInstructions());
145+
System.out.println("Harassment/Threatening: " + scores.getHarassmentThreatening());
146+
System.out.println("Violence: " + scores.getViolence());
147+
}
148+
149+
----
150+
151+
== Manual Configuration
152+
153+
Add the `spring-ai-mistral-ai` dependency to your project's Maven `pom.xml` file:
154+
155+
[source,xml]
156+
----
157+
<dependency>
158+
<groupId>org.springframework.ai</groupId>
159+
<artifactId>spring-ai-mistral-ai</artifactId>
160+
</dependency>
161+
----
162+
163+
or to your Gradle `build.gradle` build file:
164+
165+
[source,groovy]
166+
----
167+
dependencies {
168+
implementation 'org.springframework.ai:spring-ai-mistral-ai'
169+
}
170+
----
171+
172+
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
173+
174+
Next, create an MistralAiModerationModel:
175+
176+
[source,java]
177+
----
178+
MistralAiModerationApi mistralAiModerationApi = new MistralAiModerationApi(System.getenv("MISTRAL_AI_API_KEY"));
179+
180+
MistralAiModerationModel mistralAiModerationModel = new MistralAiModerationModel(this.mistralAiModerationApi);
181+
182+
MistralAiModerationOptions moderationOptions = MistralAiModerationOptions.builder()
183+
.model("mistral-moderation-latest")
184+
.build();
185+
186+
ModerationPrompt moderationPrompt = new ModerationPrompt("Text to be moderated", this.moderationOptions);
187+
ModerationResponse response = this.mistralAiModerationModel.call(this.moderationPrompt);
188+
----
189+
190+
== Example Code
191+
The `MistralAiModerationModelIT` test provides some general examples of how to use the library. You can refer to this test for more detailed usage examples.

0 commit comments

Comments
 (0)