기여 가이드라인

기여 가이드라인 (Contribution Guidelines)

Spring AI 프로젝트에 기여하려면 몇 가지 규칙을 지켜야 해요. 코드 형식을 맞추고 Javadoc을 처리한 뒤 PR을 보내야 하고, 새로운 AI 모델을 추가할 때는 정해진 단계를 따르는 게 좋아요. 이 글에서는 그 절차를 차근차근 안내해 드릴게요.

출처: 문서

본문

코드 포맷팅과 Javadoc (Code Formatting and Javadoc)

PR을 제출하기 전에 다음 명령을 실행해서 포맷팅과 Javadoc 처리가 제대로 됐는지 확인해 주세요.

./mvnw spring-javaformat:apply javadoc:javadoc -Pjavadoc

-Pjavadoc은 빌드 시간을 줄이기 위해 Javadoc 처리를 활성화하는 프로파일이에요.

새 AI 모델 구현 기여하기 (Contributing a New AI Model Implementation)

이 섹션은 새로운 AI 모델 구현을 기여하기 위한 단계를 설명해요.

AI 모델은 입력과 출력이 매우 다양해요. 텍스트 입력을 텍스트 출력으로 바꾸는 채팅 모델부터, 텍스트 설명으로 이미지를 생성하는 text-to-image 모델까지 있죠. 복잡한 모델은 텍스트, 이미지, 비디오를 조합한 혼합 미디어 출력 같은 여러 종류의 입력·출력을 다루기도 해요.

새 모델을 기여하려면 다음 단계를 따라 주세요.

  1. 저수준 클라이언트 API 클래스 만들기 (Create a Low-Level Client API Class): 해당 AI 모델에 맞는 기존 Java 클라이언트가 없다면 저수준 클라이언트 API 클래스를 직접 개발해야 해요. 이때는 MistralAiApi 클래스와 비슷하게 Spring Framework의 RestClient 클래스를 활용하는 경우가 많아요.

  2. 모델 구현 만들기 (Create a Model implementation): 클라이언트가 Generic Model API를 따르도록 해 주세요. 모델의 입력과 출력이 기존 request·response 클래스로 지원된다면 그대로 사용하고, 아니라면 Generic Model API용 새 클래스를 만들고 새 Java 패키지를 구성해 주세요. 개인 식별 정보(PII)를 로깅할 때는 PII_MARKER Slf4j 마커로 표시해 주세요.

  3. Auto-Configuration과 Spring Boot Starter 구현하기 (Implement Auto-Configuration and a Spring Boot Starter): Spring Boot 애플리케이션에서 새 모델을 쉽게 인스턴스화할 수 있도록 필요한 auto-configuration과 Spring Boot Starter를 만들어 주세요.

  4. 테스트 작성하기 (Write Tests): 모든 새 클래스에는 포괄적인 테스트가 함께 있어야 해요. 기존 테스트는 테스트를 어떻게 구조화하고 구현하는지 참고할 수 있는 좋은 예시가 됩니다.

  5. 기여 내용 문서화하기 (Document Your Contribution): 문서가 기존 형식을 따르도록 해 주세요. 권장되는 구조와 포맷의 예시는 Open AI Chat 문서를 참고해 주세요.

이 가이드라인을 따르면 공통된 구현·문서 패턴을 유지하면서 프레임워크가 지원하는 모델 범위를 크게 넓힐 수 있어요.

더 알아보기 (Learn more)