Spring/spring-ai
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update Spring AI docs build and content

Browse Source 
- Upgrade Antora Maven plugin to 1.0.0-alpha.4 (replace
  Replace the io.spring.maven.antora:antora-maven-plugin:0.0.4)
- Update playbook configuration for Antora 3.2.0-alpha.6
- Refine documentation layout and styling
- Enhance observability documentation with formatted tables
- Adjust Spring AI logo size and update integration diagram
This commit is contained in:
Christian Tzolov
2024-10-20 12:30:07 +02:00
parent 5e8cecd8b1
commit 261f18cc01
5 changed files with 78 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
spring-ai-docs/pom.xml
View File

@@ -13,23 +13,29 @@
<build>
<plugins>
<plugin>
<groupId>io.spring.maven.antora</groupId>
<groupId>org.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
<version>${io.spring.maven.antora-version}</version>
<version>1.0.0-alpha.4</version>
<extensions>true</extensions>
<configuration>
<options>
<option>--to-dir=target/antora/site</option>
<option>--stacktrace</option>
<option>--fetch</option>
</options>
<playbook>src/main/antora/antora-playbook.yml</playbook>
<packages>
<package>@antora/cli@3.2.0-alpha.6</package>
<package>@antora/atlas-extension@1.0.0-alpha.2</package>
<package>@antora/collector-extension@1.0.0-alpha.3</package>
<package>@antora/collector-extension@1.0.0-beta.1</package>
<package>@asciidoctor/tabs@1.0.0-beta.6</package>
<package>@springio/antora-extensions@1.14.2</package>
<package>@springio/asciidoctor-extensions@1.0.0-alpha.10</package>
<package>@springio/asciidoctor-extensions@1.0.0-alpha.12</package>
<package>@djencks/asciidoctor-mathjax@0.0.9</package>
</packages>
</configuration>
</plugin>
<plugin>
<!-- <plugin>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-component-version-maven-plugin</artifactId>
<version>${io.spring.maven.antora-version}</version>
@@ -40,7 +46,7 @@
</goals>
</execution>
</executions>
</plugin>
</plugin> -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>

14
spring-ai-docs/src/main/antora/antora-playbook.yml
View File

@@ -1,14 +1,18 @@
# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
# PACKAGES antora@3.2.0-alpha.6 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
#
# The purpose of this Antora playbook is to build the docs in the current branch.
antora:
extensions:
- '@antora/collector-extension'
- require: '@springio/antora-extensions/root-component-extension'
# - require: '@springio/antora-extensions/root-component-extension'
- require: '@springio/antora-extensions'
root_component_name: 'ai'
site:
title: Spring AI Reference
url: https://docs.spring.io/spring-ai/reference
robots: allow
git:
ensure_git_suffix: false
content:
sources:
- url: ./../../../..
@@ -17,6 +21,7 @@ content:
worktrees: true
asciidoc:
attributes:
page-related-doc-categories: ai,java,ml
page-pagination: ''
hide-uri-scheme: '@'
tabs-sync-option: '@'
@@ -25,11 +30,14 @@ asciidoc:
extensions:
- '@asciidoctor/tabs'
- '@springio/asciidoctor-extensions'
- '@djencks/asciidoctor-mathjax'
- '@springio/asciidoctor-extensions/javadoc-extension'
- '@springio/asciidoctor-extensions/include-code-extension'
- '@djencks/asciidoctor-mathjax'
sourcemap: true
urls:
latest_version_segment_strategy: redirect:to
latest_version_segment: ''
redirect_facility: httpd
runtime:
log:
failure_level: warn

48
spring-ai-docs/src/main/antora/modules/ROOT/images/spring-ai-integration-diagram2.svg → spring-ai-docs/src/main/antora/modules/ROOT/images/spring-ai-integration-diagram-3.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 212 KiB

After

Width:  |  Height:  |  Size: 210 KiB

5
spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc
View File

@@ -1,6 +1,6 @@
[[introduction]]
image::spring_ai_logo_with_text.svg[Integration Problem, width=400, align="left"]
image::spring_ai_logo_with_text.svg[Integration Problem, width=300, align="left"]
The `Spring AI` project aims to streamline the development of applications that incorporate artificial intelligence functionality without unnecessary complexity.
@@ -9,8 +9,7 @@ The project was founded with the belief that the next wave of Generative AI appl
NOTE: Spring AI addresses the fundamental challenge of AI integration: `Connecting your enterprise Data and APIs with the AI Models`.
// image::spring-ai-integration-diagram2.svg[Integration Problem, width=500, align="center"]
image::spring-ai-integration-diagram2.svg[Interactive,500,opts=interactive]
image::spring-ai-integration-diagram-3.svg[Interactive,500,opts=interactive]
Spring AI provides abstractions that serve as the foundation for developing AI applications.
These abstractions have multiple implementations, enabling easy component swapping with minimal code changes.

55
spring-ai-docs/src/main/antora/modules/ROOT/pages/observability/index.adoc
View File

@@ -13,9 +13,10 @@ The `spring.ai.chat.client` observations are recorded when a ChatClient `call()`
They measure the time spent performing the invocation and propagate the related tracing information.
.Low Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.operation.name` | Always `framework`.
|`gen_ai.system` | Always `spring_ai`.
|`spring.ai.chat.client.stream` | Is the chat model response a stream - `true or false`
@@ -23,9 +24,10 @@ They measure the time spent performing the invocation and propagate the related
|===
.High Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`spring.ai.chat.client.advisor.params` | Map of advisor parameters.
|`spring.ai.chat.client.advisors` | List of configured chat client advisors.
|`spring.ai.chat.client.system.params` |Chat client system parameters. Optional.
@@ -43,9 +45,10 @@ For those reasons, it is not exported by default.
Spring AI supports exporting input data as span attributes across all tracing backends.
[cols="6,3,1"]
[cols="6,3,1", stripes=even]
|====
| Property | Description | Default
| `spring.ai.chat.client.observations.include-input` | Whether to include the input content in the observations. | `false`
|====
@@ -57,9 +60,10 @@ The `spring.ai.advisor` observations are recorded when a call or stream around a
They measure the time spent in the advisor (including the time spend on the inner advisors) and propagate the related tracing information.
.Low Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.operation.name` | Always `framework`.
|`gen_ai.system` | Always `spring_ai`.
|`spring.ai.advisor.type` | Where the advisor applies it's logic in the request processing, one of `BEFORE`, `AFTER`, or `AROUND`.
@@ -67,9 +71,10 @@ They measure the time spent in the advisor (including the time spend on the inne
|===
.High Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`spring.ai.advisor.name`| Name of the advisor.
|`spring.ai.advisor.order`| Advisor order in the advisor chain.
|===
@@ -87,9 +92,10 @@ IMPORTANT: The `gen_ai.client.token.usage` metrics measures number of input and
.Low Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.operation.name` | The name of the operation being performed.
|`gen_ai.system` | The model provider as identified by the client instrumentation.
|`gen_ai.request.model` | The name of the model a request is being made to.
@@ -97,9 +103,10 @@ IMPORTANT: The `gen_ai.client.token.usage` metrics measures number of input and
|===
.High Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.request.frequency_penalty` | The frequency penalty setting for the model request.
|`gen_ai.request.max_tokens` | The maximum number of tokens the model generates for a request.
|`gen_ai.request.presence_penalty` | The presence penalty setting for the model request.
@@ -120,9 +127,10 @@ NOTE: For measuring user tokens, the previous table lists the values present in
Use the metric name `gen_ai.client.token.usage` that is provided by the `ChatModel`.
.Events
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.content.prompt` | Event including the content of the chat prompt. Optional.
|`gen_ai.content.completion` | Event including the content of the chat completion. Optional.
|===
@@ -137,9 +145,10 @@ whereas data is exported as span attributes if you use an OpenZipkin tracing bac
Furthermore, Spring AI supports logging chat prompt and completion data, useful for troubleshooting scenarios.
[cols="6,3,1"]
[cols="6,3,1", stripes=even]
|====
| Property | Description | Default
| `spring.ai.chat.observations.include-prompt` | Include the prompt content in observations. `true` or `false` | `false`
| `spring.ai.chat.observations.include-completion` | Include the completion content in observations. `true` or `false` | `false`
| `spring.ai.chat.observations.include-error-logging` | Include error logging in observations. `true` or `false` | `false`
@@ -159,9 +168,10 @@ They measure the time spent on method completion and propagate the related traci
IMPORTANT: The `gen_ai.client.token.usage` metrics measures number of input and output tokens used by a single model call.
.Low Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.operation.name` | The name of the operation being performed.
|`gen_ai.system` | The model provider as identified by the client instrumentation.
|`gen_ai.request.model` | The name of the model a request is being made to.
@@ -169,9 +179,10 @@ IMPORTANT: The `gen_ai.client.token.usage` metrics measures number of input and
|===
.High Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.request.embedding.dimensions` | The number of dimensions the resulting output embeddings have.
|`gen_ai.usage.input_tokens` | The number of tokens used in the model input.
|`gen_ai.usage.total_tokens` | The total number of tokens used in the model exchange.
@@ -193,9 +204,10 @@ IMPORTANT: The `gen_ai.client.token.usage` metrics measures number of input and
.Low Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.operation.name`| The name of the operation being performed.
|`gen_ai.system`| The model provider as identified by the client instrumentation.
|`gen_ai.request.model`| The name of the model a request is being made to.
@@ -204,6 +216,7 @@ IMPORTANT: The `gen_ai.client.token.usage` metrics measures number of input and
.High Cardinality Keys
|===
|Name | Description
|`gen_ai.request.image.response_format` | The format in which the generated image is returned.
|`gen_ai.request.image.size` | The size of the image to generate.
|`gen_ai.request.image.style` | The style of the image to generate.
@@ -219,9 +232,10 @@ NOTE: For measuring user tokens, the previous table lists the values present in
Use the metric name `gen_ai.client.token.usage` that is provided by the `ImageModel`.
.Events
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`gen_ai.content.prompt` | Event including the content of the image prompt. Optional.
|===
@@ -233,9 +247,10 @@ For those reasons, it is not exported by default.
Spring AI supports exporting image prompt data as span events if you use an OpenTelemetry tracing backend,
whereas data is exported as span attributes if you use an OpenZipkin tracing backend.
[cols="6,3,1"]
[cols="6,3,1", stripes=even]
|===
| Property | Description | Default
| `spring.ai.image.observations.include-prompt` | `true` or `false` | `false`
|===
@@ -249,18 +264,20 @@ The `db.vector.client.operation` observations are recorded when interacting with
They measure the time spent on the `query`, `add` and `remove` operations and propagate the related tracing information.
.Low Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`db.operation.name` | The name of the operation or command being executed. One of `add`, `delete`, or `query`.
|`db.system` | The database management system (DBMS) product as identified by the client instrumentation. One of `pg_vector`, `azure`, `cassandra`, `chroma`, `elasticsearch`, `milvus`, `neo4j`, `opensearch`, `qdrant`, `redis`, `typesense`, `weaviate`, `pinecone`, `oracle`, `mongodb`, `gemfire`, `hana`, `simple`.
|`spring.ai.kind` | The kind of framework API in Spring AI: `vector_store`.
|===
.High Cardinality Keys
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`db.collection.name` | The name of a collection (table, container) within the database.
|`db.namespace` | The name of the database, fully qualified within the server address and port.
|`db.record.id` | The record identifier if present.
@@ -275,9 +292,10 @@ They measure the time spent on the `query`, `add` and `remove` operations and pr
|===
.Events
[cols="a,a"]
[cols="a,a", stripes=even]
|===
|Name | Description
|`db.vector.content.query.response` | Event including the vector search response data. Optional.
|===
@@ -289,9 +307,10 @@ For those reasons, it is not exported by default.
Spring AI supports exporting vector search response data as span events if you use an OpenTelemetry tracing backend,
whereas data is exported as span attributes if you use an OpenZipkin tracing backend.
[cols="6,3,1"]
[cols="6,3,1", stripes=even]
|===
| Property | Description | Default
| `spring.ai.vectorstore.observations.include-query-response` | `true` or `false` | `false`
|===