# RAGFlow 배포 ## 1. 배포 방법 - 명령어 ``` sh $ helm upgrade ragflow ../ragflow --install \ --namespace ragflow \ -f ./custom-values.yaml \ --create-namespace ``` ## 2. custom-values.yaml 설명 - custom-values.yaml에 정의된 값에 대한 설명이다. ### 1) 환경 변수 설정 - RAGFlow 및 관련 서비스들의 환경 변수를 설정한다. | Name | 설명 | 기본값 | | ---------------------- | ------------------------------------------------------------ | ------ | | `env.DOC_ENGINE` | 문서 엔진 타입 설정. `elasticsearch`, `infinity`, `opensearch` 선택 가능 | `infinity` | | `env.STACK_VERSION` | Elasticsearch 버전 설정 | `"8.11.3"` | | `env.ELASTIC_PASSWORD` | Elasticsearch 비밀번호 | `infini_rag_flow_helm` | | `env.OPENSEARCH_PASSWORD` | OpenSearch 비밀번호 (대소문자, 숫자, 특수문자 포함 필요) | `infini_rag_flow_OS_01` | | `env.MYSQL_PASSWORD` | MySQL 비밀번호 | `infini_rag_flow_helm` | | `env.MYSQL_DBNAME` | MySQL 데이터베이스 이름 | `rag_flow` | | `env.MINIO_ROOT_USER` | MinIO 사용자명 | `rag_flow` | | `env.MINIO_PASSWORD` | MinIO 비밀번호 | `infini_rag_flow_helm` | | `env.REDIS_PASSWORD` | Redis 비밀번호 | `infini_rag_flow_helm` | | `env.RAGFLOW_IMAGE` | RAGFlow Docker 이미지 | `infiniflow/ragflow:v0.20.1-slim` | | `env.REQUESTS_CA_BUNDLE` | 사설 인증서 사용 시 CA 번들 파일 경로 | 설정하지 않음 | | `env.SSL_CERT_FILE` | SSL 인증서 파일 경로 (사설 인증서 사용 시) | 설정하지 않음 | | `env.TIMEZONE` | 로컬 시간대 설정 | `"Asia/Seoul"` | | `env.DOC_BULK_SIZE` | 문서 파싱 시 단일 배치에서 처리되는 문서 청크 수 | `4` | | `env.EMBEDDING_BATCH_SIZE` | 임베딩 벡터화 시 단일 배치에서 처리되는 텍스트 청크 수 | `16` | ### 2) RAGFlow 서비스 설정 - RAGFlow 메인 서비스의 설정을 관리한다. | Name | 설명 | 기본값 | | ------------------------ | ---------------------------------- | --------- | | `ragflow.service.type` | RAGFlow 서비스 타입 설정 | `ClusterIP` | | `ragflow.api.service.enabled` | API 서비스 활성화 여부 | `true` | | `ragflow.api.service.type` | API 서비스 타입 설정 | `ClusterIP` | | `ragflow.deployment.strategy` | 배포 전략 설정 | `` | | `ragflow.deployment.resources` | 리소스 제한 설정 | `` | | `ragflow.service_conf.oauth.oidc` | OIDC 인증 설정 | 설정 예시 참조 | | `ragflow.llm_factories` | LLM 팩토리 설정 | 설정 예시 참조 | | `ragflow.volumes` | 추가 볼륨 설정 | `[]` | | `ragflow.volumeMounts` | 추가 볼륨 마운트 설정 | `[]` | #### 2.1) OIDC 인증 설정 예시 ```yaml ragflow: service_conf: oauth: oidc: display_name: "OIDC" client_id: "ragflow" client_secret: "your-client-secret" issuer: "https://your-keycloak-domain/realms/your-realm" scope: "openid email profile" redirect_uri: "https://your-ragflow-domain/v1/user/oauth/callback/oidc" ``` #### 2.2) LLM 팩토리 설정 예시 ```yaml ragflow: llm_factories: factory_llm_infos: - name: OpenAI-API-Compatible logo: "" tags: "LLM,TEXT EMBEDDING,SPEECH2TEXT,MODERATION" status: "1" llm: - llm_name: my-custom-llm tags: "LLM,CHAT," max_tokens: 100000 model_type: chat is_tools: false ``` #### 2.3) 사설 인증서 설정 예시 ```yaml env: # 사설 인증서 사용 시 CA 번들 파일 경로 설정 REQUESTS_CA_BUNDLE: /tmp/ca.crt SSL_CERT_FILE: /tmp/ca.crt ragflow: # 사설 인증서를 포함한 Secret을 볼륨으로 마운트 volumes: - name: keycloak-tls secret: secretName: keycloak-tls # Secret의 ca.crt를 컨테이너 내부 경로에 마운트 volumeMounts: - name: keycloak-tls mountPath: /tmp/ca.crt subPath: ca.crt readOnly: true ``` #### 2.4) 추가 볼륨 및 볼륨 마운트 설정 예시 ```yaml ragflow: # 다양한 타입의 볼륨 설정 예시 volumes: # ConfigMap 볼륨 - name: my-config configMap: name: my-configmap # Secret 볼륨 - name: my-secret secret: secretName: my-secret # PVC 볼륨 - name: my-data persistentVolumeClaim: claimName: my-pvc # 볼륨 마운트 설정 예시 volumeMounts: # ConfigMap 마운트 - name: my-config mountPath: /app/config readOnly: true # Secret의 특정 키만 마운트 - name: my-secret mountPath: /app/secrets/token subPath: token readOnly: true # PVC 마운트 - name: my-data mountPath: /app/data ``` ### 3) Infinity 서비스 설정 - Infinity 문서 엔진 서비스 설정 (DOC_ENGINE이 infinity일 때 사용) | Name | 설명 | 기본값 | | --------------------------- | ------------------------------------------------------------ | ----------------------- | | `infinity.image.repository` | Infinity 이미지 저장소 | `infiniflow/infinity` | | `infinity.image.tag` | Infinity 이미지 태그 | `v0.6.0-dev5` | | `infinity.storage.className` | 스토리지 클래스 이름 | `` | | `infinity.storage.capacity` | 스토리지 용량 | `5Gi` | | `infinity.deployment.strategy` | 배포 전략 설정 | `` | | `infinity.deployment.resources` | 리소스 제한 설정 | `` | | `infinity.service.type` | 서비스 타입 | `ClusterIP` | ### 4) Elasticsearch 서비스 설정 - Elasticsearch 문서 엔진 서비스 설정 (DOC_ENGINE이 elasticsearch일 때 사용) | Name | 설명 | 기본값 | | --------------------------- | ------------------------------------------------------------ | ----------------------- | | `elasticsearch.storage.className` | 스토리지 클래스 이름 | `` | | `elasticsearch.storage.capacity` | 스토리지 용량 | `20Gi` | | `elasticsearch.deployment.resources.requests.cpu` | CPU 요청량 | `"4"` | | `elasticsearch.deployment.resources.requests.memory` | 메모리 요청량 | `"16Gi"` | | `elasticsearch.service.type` | 서비스 타입 | `ClusterIP` | ### 5) MinIO 서비스 설정 - 객체 스토리지 서비스 설정 | Name | 설명 | 기본값 | | --------------------------- | ------------------------------------------------------------ | ----------------------- | | `minio.image.repository` | MinIO 이미지 저장소 | `quay.io/minio/minio` | | `minio.image.tag` | MinIO 이미지 태그 | `RELEASE.2023-12-20T01-00-02Z` | | `minio.storage.className` | 스토리지 클래스 이름 | `` | | `minio.storage.capacity` | 스토리지 용량 | `5Gi` | | `minio.service.type` | 서비스 타입 | `ClusterIP` | ### 6) MySQL 서비스 설정 - 관계형 데이터베이스 서비스 설정 | Name | 설명 | 기본값 | | --------------------------- | ------------------------------------------------------------ | ----------------------- | | `mysql.image.repository` | MySQL 이미지 저장소 | `mysql` | | `mysql.image.tag` | MySQL 이미지 태그 | `8.0.39` | | `mysql.storage.className` | 스토리지 클래스 이름 | `` | | `mysql.storage.capacity` | 스토리지 용량 | `5Gi` | | `mysql.service.type` | 서비스 타입 | `ClusterIP` | ### 7) Redis 서비스 설정 - 캐시 및 세션 스토리지 서비스 설정 | Name | 설명 | 기본값 | | --------------------------- | ------------------------------------------------------------ | ----------------------- | | `redis.image.repository` | Redis 이미지 저장소 | `valkey/valkey` | | `redis.image.tag` | Redis 이미지 태그 | `8` | | `redis.storage.className` | 스토리지 클래스 이름 | `` | | `redis.storage.capacity` | 스토리지 용량 | `5Gi` | | `redis.persistence.enabled` | 데이터 영속성 활성화 | `true` | | `redis.service.type` | 서비스 타입 | `ClusterIP` | ### 8) Ingress 설정 #### 8.1) 기본 Ingress 설정 - RAGFlow 웹 인터페이스 외부 노출을 위한 Ingress 설정 ``` yaml ingress: enabled: true className: "kong" hosts: - host: ragflow.example.org paths: - path: / pathType: ImplementationSpecific tls: - secretName: ragflow-tls hosts: - ragflow.example.org ``` #### 8.2) TLS 시크릿 직접 생성 - Ingress 사용을 위해서는 인증서를 secret으로 제공해야한다. 로컬 파일을 이용해 secret을 생성하는 방법은 다음과 같다. ``` sh kubectl create secret tls ragflow-tls --cert= --key= -n ``` #### 8.3) cert-manager를 이용한 자동 생성 - cert manager를 통해 인증서 자동 생성 시 `custom-values.yaml` 수정한다. - `ingress.annotations.cert-manager.io/cluster-issuer`에 미리 배포된 Cluster Issuer의 이름으로 변경한다. ``` yaml ingress: enabled: true className: "kong" annotations: cert-manager.io/cluster-issuer: "selfsigned-issuer" cert-manager.io/duration: 8760h cert-manager.io/renew-before: 720h konghq.com/https-redirect-status-code: '301' konghq.com/protocols: https hosts: - host: ragflow.example.org paths: - path: / pathType: ImplementationSpecific tls: - hosts: - ragflow.example.org secretName: ragflow-tls ``` #### 8.4) Kong 관련 어노테이션 - Kong Ingress Controller 사용 시 추가 설정 옵션들: | Name | 설명 | 기본값 | | --------------------------------------- | ---------------------------------- | --------- | | `konghq.com/https-redirect-status-code` | HTTPS 리다이렉트 상태 코드 | `'301'` | | `konghq.com/protocols` | 허용할 프로토콜 | `https` | ## 3. 주요 설정 가이드 ### 3.1) 문서 엔진 선택 - `env.DOC_ENGINE`을 통해 문서 엔진을 선택할 수 있습니다. - `elasticsearch`: 안정적이고 검증된 검색 엔진 - `infinity`: 고성능 벡터 검색 엔진 (권장) - `opensearch`: Elasticsearch의 오픈소스 대안 ### 3.2) 리소스 설정 - 각 서비스별로 `deployment.resources`에서 CPU/메모리 리소스를 설정할 수 있습니다. - Elasticsearch는 기본적으로 4 CPU, 16Gi 메모리를 요청합니다. ### 3.3) 스토리지 설정 - 모든 서비스에서 `storage.className`을 통해 스토리지 클래스를 지정할 수 있습니다. - 각 서비스별로 적절한 스토리지 용량을 설정하세요. ### 3.4) 보안 설정 - 모든 비밀번호는 기본값에서 변경하여 사용하세요. - OIDC를 통한 외부 인증 시스템 연동이 가능합니다. ### 3.5) 성능 튜닝 설정 - 문서 처리 및 임베딩 성능을 조정할 수 있는 설정들입니다. | Name | 설명 | 기본값 | | --------------------------- | ------------------------------------------------------------ | ----------------------- | | `env.DOC_BULK_SIZE` | 문서 파싱 시 단일 배치에서 처리되는 문서 청크 수 | `4` | | `env.EMBEDDING_BATCH_SIZE` | 임베딩 벡터화 시 단일 배치에서 처리되는 텍스트 청크 수 | `16` | ### 3.6) 사설 인증서 설정 - HTTPS 통신 시 사설 인증서를 사용하는 경우의 설정 방법입니다. #### 3.6.1) 사설 인증서 Secret 생성 ```sh # CA 인증서 파일로부터 Secret 생성 kubectl create secret generic keycloak-tls \ --from-file=ca.crt=/path/to/ca.crt \ -n ``` #### 3.6.2) values.yaml 설정 ```yaml env: # Python requests 라이브러리가 사용할 CA 번들 파일 경로 REQUESTS_CA_BUNDLE: /tmp/ca.crt SSL_CERT_FILE: /tmp/ca.crt ragflow: volumes: - name: keycloak-tls secret: secretName: keycloak-tls volumeMounts: - name: keycloak-tls mountPath: /tmp/ca.crt subPath: ca.crt readOnly: true ``` #### 3.6.3) 주의사항 - `REQUESTS_CA_BUNDLE`와 `SSL_CERT_FILE`의 경로는 `volumeMounts.mountPath`와 일치해야 합니다. - `subPath`를 사용하여 Secret의 특정 키만 마운트하는 것을 권장합니다. - 인증서 파일은 읽기 전용(`readOnly: true`)으로 마운트하세요. ### 3.7) 추가 환경 설정 - 기타 선택적 환경 설정들입니다. | Name | 설명 | 기본값 | | --------------------------- | ------------------------------------------------------------ | ----------------------- | | `env.HF_ENDPOINT` | Hugging Face 엔드포인트 (접근 제한 시 미러 사용) | 설정하지 않음 | | `env.MAX_CONTENT_LENGTH` | 업로드 파일 최대 크기 (바이트) | `134217728` (128MB) | **참고**: `MAX_CONTENT_LENGTH` 변경 시 nginx 설정의 `client_max_body_size`도 함께 수정해야 합니다.