Configuration Guide

This guide details the various configuration options available for sd-webui-infinite-image-browsing, allowing you to customize its behavior, performance, privacy, and integration with AI features. Configurations can be applied via environment variables or command-line arguments when running the standalone app.py.

General Application Settings

Database File Location

• IIB_DB_PATH (Environment Variable)
  • Description: Specifies the path to the SQLite database file (iib.db) used for storing image metadata and tags.
  • Default: iib.db in the application's current working directory.
  • Usage: export IIB_DB_PATH="/path/to/your/custom/iib.db"

Cache Directory

• IIB_CACHE_DIR (Environment Variable)
  • Description: Defines the directory where generated image thumbnails and video covers are stored.
  • Default: A temporary directory determined by the operating system (TMPDIR, TMP, TEMP environment variables, or Python's tempfile.gettempdir()).
  • Usage: export IIB_CACHE_DIR="/path/to/your/custom/cache"

Application Host and Port

When running app.py as a standalone application:

• --host (Command-line Argument)
  • Description: Specifies the host address for the application.
  • Default: 127.0.0.1
  • Usage: python app.py --host 0.0.0.0
• --port (Command-line Argument)
  • Description: Specifies the port for the application.
  • Default: 8000
  • Usage: python app.py --port 7860

Pre-generation of Caches

These command-line arguments are used for pre-generating caches, which can significantly improve browsing performance, especially for large media libraries. They are typically run as separate commands and will exit after completion.

• --generate_video_cover (Command-line Argument)
  • Description: Pre-generates video cover images for faster browsing.
  • Usage: python app.py --generate_video_cover
• --generate_image_cache (Command-line Argument)
  • Description: Pre-generates image thumbnails to speed up image browsing. By default, only user-added extra paths are processed. For SD-webui paths, --sd_webui_config and --sd_webui_path_relative_to_config must also be used.
  • Usage: python app.py --generate_image_cache --sd_webui_config config.json
• --generate_image_cache_size (Command-line Argument)
  • Description: Sets the size of the image cache to generate.
  • Default: 512x512
  • Usage: python app.py --generate_image_cache --generate_image_cache_size 256x256
• --gen_cache_verbose (Command-line Argument)
  • Description: Enables verbose output during cache generation, showing detailed progress.
  • Usage: python app.py --generate_image_cache --gen_cache_verbose

Database Backup

• IIB_DB_FILE_BACKUP_MAX (Environment Variable)
  • Description: Sets the maximum number of database backup files to retain. Older backups will be automatically removed.
  • Default: 8
  • Usage: export IIB_DB_FILE_BACKUP_MAX=5

Server Language

• IIB_SERVER_LANG (Environment Variable)
  • Description: Forces the server-side language for logs and messages.
  • Supported Values: zh, en
  • Default: Automatically detected based on system locale.
  • Usage: export IIB_SERVER_LANG="en"

SD-WebUI Integration and Paths

SD-WebUI Configuration File

• --sd_webui_config (Command-line Argument)
  • Description: Specifies the path to the config.json file of your Stable Diffusion web UI installation. This allows IIB to automatically discover your generated image directories.
  • Default: None (IIB will try to auto-detect if running as an extension)
  • Usage: python app.py --sd_webui_config /path/to/sd-webui/config.json
• --sd_webui_path_relative_to_config (Command-line Argument)
  • Description: When specified, all relative paths defined within the sd_webui_config file will be resolved relative to the sd_webui_config file's location.
  • Usage: python app.py --sd_webui_config /path/to/sd-webui/config.json --sd_webui_path_relative_to_config
• --sd_webui_dir (Command-line Argument)
  • Description: Specifies the path to the root folder of the SD-WebUI installation. This is primarily used for the desktop application to configure IIB and share data.
  • Default: None
  • Usage: python app.py --sd_webui_dir /path/to/sd-webui

Image Directories from SD-WebUI

IIB automatically indexes images from these paths, as configured in your sd_webui_config.json:

• outdir_txt2img_samples
• outdir_img2img_samples
• outdir_save
• outdir_extras_samples
• outdir_grids
• outdir_img2img_grids
• outdir_samples
• outdir_txt2img_grids

Additional Image Paths

• --extra_paths (Command-line Argument)
  • Description: Allows specifying additional directories to be displayed on the IIB homepage. Images in these paths are viewable but not indexed by default for search. To index them, add them via the + Add button on the homepage.
  • Usage: python app.py --extra_paths /path/to/images1 /path/to/images2

Frontend Function Export

• --export_fe_fn (Command-line Argument)
  • Description: Exports frontend functions, enabling external applications (e.g., via iframe) to interact with IIB.
  • Default: True
  • Usage: python app.py --export_fe_fn False

API Base URL

• --base (Command-line Argument)
  • Description: Specifies the base URL for the IIB API. Useful for reverse proxies or specific deployment scenarios.
  • Default: /infinite_image_browsing
  • Usage: python app.py --base /my-iib-instance

Privacy and Security

Secret Key Authentication

• IIB_SECRET_KEY (Environment Variable)
  • Description: Configures a secret key required to access the IIB API. This is crucial for security, especially when IIB is publicly exposed.
  • Default: None (No secret key required by default)
  • Usage: export IIB_SECRET_KEY="your_secure_secret_key"
  • Note: If gradio-auth is configured for SD-WebUI, IIB will automatically require a secret key even if IIB_SECRET_KEY is not set.

Access Control

• IIB_ACCESS_CONTROL (Environment Variable)
  • Description: Controls whether file system access control is enabled.
  • Supported Values: enable, disable
  • Default: enable if SD-WebUI is running with --share, --ngrok, --listen, or --server_name. Otherwise, disable.
  • Usage: export IIB_ACCESS_CONTROL="enable"
• IIB_ACCESS_CONTROL_ALLOWED_PATHS (Environment Variable)
  • Description: A comma-separated list of absolute paths that IIB is allowed to access. Can also include special keywords like save, extra, txt2img, img2img which map to corresponding paths in sd_webui_config.
  • Default: All scanned image directories from SD-WebUI and --extra_paths.
  • Usage: export IIB_ACCESS_CONTROL_ALLOWED_PATHS="/path/to/safe_folder1,/path/to/safe_folder2,save,extra"
• IIB_ACCESS_CONTROL_PERMISSION (Environment Variable)
  • Description: Defines the file system permissions for IIB.
  • Supported Values: read-write, read-only, write-only
  • Default: read-write
  • Usage: export IIB_ACCESS_CONTROL_PERMISSION="read-only"
• --allow_cors (Command-line Argument)
  • Description: Enables Cross-Origin Resource Sharing (CORS) for the API, allowing requests from different origins.
  • Default: False
  • Usage: python app.py --allow_cors
• --enable_shutdown (Command-line Argument)
  • Description: Enables a /shutdown API endpoint. Primarily used by the desktop application for controlled shutdown. Not recommended for public-facing deployments.
  • Default: False
  • Usage: python app.py --enable_shutdown

AI / Natural Language Features (Topic Clustering & Tag Graph)

These settings control the experimental natural language categorization, search, and tag graph features, which rely on OpenAI-compatible API endpoints for embeddings and chat models.

API Credentials and Endpoints

• OPENAI_API_KEY (Environment Variable)
  • Description: Your API key for accessing OpenAI-compatible services.
  • Default: ""
  • Usage: export OPENAI_API_KEY="sk-your_openai_key"
• OPENAI_BASE_URL (Environment Variable)
  • Description: The base URL for your OpenAI-compatible API endpoint.
  • Default: https://api.openai.com/v1
  • Usage: export OPENAI_BASE_URL="https://your-custom-llm-host/v1"

AI Models

• AI_MODEL (Environment Variable)
  • Description: The default chat model to use for AI-related tasks, including fallback for topic title generation if TOPIC_TITLE_MODEL is not set.
  • Default: gpt-4o-mini
  • Usage: export AI_MODEL="gpt-3.5-turbo"
• EMBEDDING_MODEL (Environment Variable)
  • Description: The embedding model used for generating vector representations of image prompts, crucial for semantic similarity search and clustering.
  • Default: text-embedding-3-small
  • Usage: export EMBEDDING_MODEL="text-embedding-ada-002"
• TOPIC_TITLE_MODEL (Environment Variable)
  • Description: The specific chat model to use for generating human-readable titles and keywords for image clusters. If not set, falls back to AI_MODEL.
  • Default: AI_MODEL
  • Usage: export TOPIC_TITLE_MODEL="gpt-4o-mini"

Prompt Normalization

These settings control how image prompts are cleaned and normalized before being sent to the embedding model, aiming to improve the semantic quality of clustering and search results by removing boilerplate text.

• IIB_PROMPT_NORMALIZE (Environment Variable)
  • Description: Enables or disables prompt normalization.
  • Supported Values: 1 (enable), 0 (disable), true, false, yes, no, on, off
  • Default: 1 (enabled)
  • Usage: export IIB_PROMPT_NORMALIZE="0"
• IIB_PROMPT_NORMALIZE_MODE (Environment Variable)
  • Description: Sets the aggressiveness of prompt normalization.
  • Supported Values:
    • balanced (recommended): Keeps some discriminative style words (e.g., "scientific illustration") while dropping common quality/camera terms.
    • theme_only: More aggressive removal, focusing on "only subject/theme nouns."
  • Default: balanced
  • Usage: export IIB_PROMPT_NORMALIZE_MODE="theme_only"

Tag Graph Generation

These environment variables fine-tune the behavior of the hierarchical tag graph feature, especially concerning LLM interactions.

• IIB_TAG_GRAPH_MAX_TAGS_FOR_LLM (Environment Variable)
  • Description: Maximum number of tags (from the Tag layer) to send to the LLM for abstraction to higher layers. Higher values can lead to better abstraction but increased LLM cost/latency.
  • Default: 500
  • Usage: export IIB_TAG_GRAPH_MAX_TAGS_FOR_LLM=200
• IIB_TAG_GRAPH_TOPK_TAGS_FOR_LLM (Environment Variable)
  • Description: Top K tags by frequency/weight to consider when generating LLM abstraction layers in the tag graph. This helps control prompt size for very large tag sets.
  • Default: 500
  • Usage: export IIB_TAG_GRAPH_TOPK_TAGS_FOR_LLM=300
• IIB_TAG_GRAPH_LLM_TIMEOUT_SEC (Environment Variable)
  • Description: Timeout in seconds for individual LLM requests during tag graph generation.
  • Default: 180
  • Usage: export IIB_TAG_GRAPH_LLM_TIMEOUT_SEC=300
• IIB_TAG_GRAPH_LLM_MAX_ATTEMPTS (Environment Variable)
  • Description: Maximum number of retry attempts for LLM calls if they fail due to network or API errors.
  • Default: 5
  • Usage: export IIB_TAG_GRAPH_LLM_MAX_ATTEMPTS=3

ComfyUI Parser

• IIB_COMFYUI_EXTRACT_ALL_PROMPTS (Environment Variable)
  • Description: If set to true, the ComfyUI parser will attempt to extract all available prompt texts from the workflow and combine them into the positive prompt field. This can be useful for workflows that don't clearly separate positive/negative prompts in the typical prompt and workflow fields.
  • Default: false
  • Usage: export IIB_COMFYUI_EXTRACT_ALL_PROMPTS="true"

SD-WebUI Stealth PNG Info Parser

• IIB_ENABLE_SD_WEBUI_STEALTH_PARSER (Environment Variable)
  • Description: Enables the parser for images generated with the sd-webui-stealth-pnginfo extension, which hides metadata in image pixels.
  • Default: false
  • Usage: export IIB_ENABLE_SD_WEBUI_STEALTH_PARSER="true"