feat:Update OpenAPI specification for Jina Embedding Serving API endpoints and schemas

[HavenDV]

Summary by CodeRabbit

• New Features

  • Introduced a new endpoint for creating multiple vector representations of input texts (/v1/multi-vector).
  • Updated the /v1/train endpoint description for better clarity.

• Improvements

  • Enhanced schema definitions with new properties for email capture in bulk embedding requests and responses.
  • Updated example values for various document schemas to a unique identifier format.

• Deprecations

  • Marked the /v1/multi-embeddings endpoint as deprecated.

[coderabbitai]

Walkthrough

The changes involve modifications to the OpenAPI specification for the Jina Embedding Serving API. Key updates include the deprecation of the /v1/multi-embeddings endpoint, the introduction of the new /v1/multi-vector endpoint, and clarifications to the /v1/train endpoint's description. Additionally, several schema definitions have been updated, including the addition of new properties to existing schemas and changes to example values. The security scheme remains unchanged, continuing to use HTTP Bearer authentication.

Changes

File Path

Change Summary

src/libs/Jina/openapi.yaml

- Deprecated /v1/multi-embeddings endpoint. - Added /v1/multi-vector endpoint. - Updated /v1/train description. - Modified Body_start_bulk_embedding_v1_bulk_embeddings_post schema to include email property. - Updated BulkEmbeddingJobResponse schema to include user_email property. - Changed example values for several schemas: ImageExampleDoc, TextExampleDoc, api_schemas__classification__TextDoc, api_schemas__embedding__ImageDoc, api_schemas__embedding__TextDoc, api_schemas__rank__TextDoc.

Poem

In the garden where vectors play,
A new path blooms, bright as the day.
Old endpoints wave their last goodbye,
While fresh ones leap, oh my, oh my!
With emails added, clarity's near,
Hopping forward, we cheer and cheer! 🐇✨

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 0

🧹 Outside diff range and nitpick comments (3)

src/libs/Jina/openapi.yaml (3)

Line range hint 312-339: Approve new /v1/multi-vector endpoint with a suggestion for clarity.

The addition of the /v1/multi-vector endpoint is a good improvement, providing functionality to create multiple vector representations of input texts. This appears to be a replacement for the deprecated /v1/multi-embeddings endpoint.

To improve clarity, consider adding a brief explanation of how this differs from the standard embedding endpoint. For example, you could add:
"Unlike the standard embedding endpoint, this endpoint creates a separate vector for each token in the input text, which can be useful for certain advanced retrieval techniques."

---

Line range hint 340-367: Enhance deprecation notice for /v1/multi-embeddings endpoint.

The /v1/multi-embeddings endpoint has been correctly marked as deprecated. To further assist API users, consider adding migration information to the description. For example:

description: |
  Create multiple vector representations of the given input texts. One vector representation for each token in the input text.
  DEPRECATED: This endpoint is deprecated and will be removed in a future version. Please use the `/v1/multi-vector` endpoint instead.

This addition will help guide users towards the new endpoint and ensure a smoother transition.

---

Line range hint 376-380: Approve addition of email property with naming consistency suggestion.

The addition of the email property to the Body_start_bulk_embedding_v1_bulk_embeddings_post schema is approved. This allows for associating the bulk embedding job with a specific user email.

For consistency, consider renaming this property to user_email to match the corresponding field in the BulkEmbeddingJobResponse schema. This would make the API more intuitive and easier to understand.

Also, ensure that the same privacy considerations mentioned for the user_email in the response are applied here as well.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL

📥 Commits

Files that changed from the base of the PR and between 7e5e5db and 0390ed0.

⛔ Files ignored due to path filters (7)

• src/libs/Jina/Generated/Jina.Models.ApiSchemasClassificationImageDoc.g.cs is excluded by !**/generated/**
• src/libs/Jina/Generated/Jina.Models.ApiSchemasClassificationTextDoc.g.cs is excluded by !**/generated/**
• src/libs/Jina/Generated/Jina.Models.ApiSchemasEmbeddingImageDoc.g.cs is excluded by !**/generated/**
• src/libs/Jina/Generated/Jina.Models.ApiSchemasEmbeddingTextDoc.g.cs is excluded by !**/generated/**
• src/libs/Jina/Generated/Jina.Models.ApiSchemasRankTextDoc.g.cs is excluded by !**/generated/**
• src/libs/Jina/Generated/Jina.Models.ImageExampleDoc.g.cs is excluded by !**/generated/**
• src/libs/Jina/Generated/Jina.Models.TextExampleDoc.g.cs is excluded by !**/generated/**

📒 Files selected for processing (1)

• src/libs/Jina/openapi.yaml (7 hunks)

🧰 Additional context used

🔇 Additional comments (6)

src/libs/Jina/openapi.yaml (6)

581-581: Update example ID to use a more realistic format.

The example ID for the ImageExampleDoc schema has been updated to use a more realistic format. This change improves the clarity of the documentation.

---

948-948: Update example ID to use a more realistic format.

Similar to the ImageExampleDoc, the example ID for the TextExampleDoc schema has been updated to use a more realistic format. This change maintains consistency across the documentation.

---

1066-1066: Consistent update of example IDs across multiple schemas.

The example IDs for various schemas (api_schemas__classification__ImageDoc, api_schemas__classification__TextDoc, api_schemas__embedding__ImageDoc, api_schemas__embedding__TextDoc, and api_schemas__rank__TextDoc) have all been updated to use the same realistic format. This change ensures consistency across the API documentation and improves readability.

Also applies to: 1100-1100, 1128-1128, 1162-1162, 1192-1192

---

Line range hint 106-110: Approve addition of user_email with privacy consideration.

The addition of the user_email property to the BulkEmbeddingJobResponse schema is approved. This can be useful for tracking and notification purposes.

However, please ensure that appropriate measures are in place to protect user privacy:

1. Confirm that the email is only returned to authenticated users with the appropriate permissions.
2. Consider whether this field should be optional, depending on user privacy settings.
3. Ensure compliance with relevant data protection regulations (e.g., GDPR) when storing and transmitting this information.

---

581-581: Approve consistent update of example IDs across schemas.

The update of example IDs to use a more realistic format (MD5-like hash) across multiple schemas is approved. This change improves the consistency and realism of the API documentation, making it easier for developers to understand the expected format of IDs.

The affected schemas include:

• ImageExampleDoc
• TextExampleDoc
• api_schemas__classification__ImageDoc
• api_schemas__classification__TextDoc
• api_schemas__embedding__ImageDoc
• api_schemas__embedding__TextDoc
• api_schemas__rank__TextDoc

This consistent approach enhances the overall quality of the API specification.

Also applies to: 948-948, 1066-1066, 1100-1100, 1128-1128, 1162-1162, 1192-1192

---

Line range hint 1-1228: Overall approval with minor suggestions for improvement.

The changes to the OpenAPI specification for the Jina Embedding Serving API are generally well-implemented and enhance the API's functionality and documentation. Key improvements include:

1. Addition of the new /v1/multi-vector endpoint.
2. Deprecation of the /v1/multi-embeddings endpoint.
3. Updates to various schemas to include new properties like user_email.
4. Consistent update of example IDs across multiple schemas.

These changes should improve the API's usability and provide better support for advanced embedding techniques. To further enhance the specification:

1. Consider adding more detailed migration guidance for the deprecated endpoint.
2. Ensure consistency in naming conventions (e.g., email vs user_email).
3. Review and update the security and privacy considerations for new user-related fields.

Overall, these changes represent a positive evolution of the API specification.