service-catalog/manifests/helm/ragflow/0.1.0/CUSTOM-README.md

# 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=<path-to-cert-file> --key=<path-to-key-file> -n <namespace>
  ```

#### 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 <namespace>
```

#### 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`도 함께 수정해야 합니다.