{"id":51456802,"url":"https://github.com/mukoubuchi/vector-search-hands-on","last_synced_at":"2026-07-06T01:02:10.898Z","repository":{"id":364318653,"uuid":"1261873538","full_name":"mukoubuchi/vector-search-hands-on","owner":"mukoubuchi","description":"Milvus-based vector search hands-on using IBM Bob, Building Blocks, FastAPI, and Hugging Face embeddings","archived":false,"fork":false,"pushed_at":"2026-07-05T03:50:47.000Z","size":2321,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T05:15:05.466Z","etag":null,"topics":["building-blocks","embeddings","fastapi","github-pages","hands-on","huggingface","ibm-bob","milvus","mkdocs","sentence-transformers","vector-search","workshop"],"latest_commit_sha":null,"homepage":"https://mukoubuchi.github.io/vector-search-hands-on/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mukoubuchi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T09:11:51.000Z","updated_at":"2026-07-05T03:50:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"6a47f241-ff6f-454c-8dd9-3ecf3bbe3d35","html_url":"https://github.com/mukoubuchi/vector-search-hands-on","commit_stats":null,"previous_names":["mukoubuchi/vector-search-hands-on"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mukoubuchi/vector-search-hands-on","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukoubuchi%2Fvector-search-hands-on","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukoubuchi%2Fvector-search-hands-on/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukoubuchi%2Fvector-search-hands-on/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukoubuchi%2Fvector-search-hands-on/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mukoubuchi","download_url":"https://codeload.github.com/mukoubuchi/vector-search-hands-on/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mukoubuchi%2Fvector-search-hands-on/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35174071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["building-blocks","embeddings","fastapi","github-pages","hands-on","huggingface","ibm-bob","milvus","mkdocs","sentence-transformers","vector-search","workshop"],"created_at":"2026-07-06T01:02:09.443Z","updated_at":"2026-07-06T01:02:10.884Z","avatar_url":"https://github.com/mukoubuchi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vector Search Hands-on\n\n[![CI](https://img.shields.io/github/actions/workflow/status/mukoubuchi/vector-search-hands-on/ci.yml?branch=main\u0026label=CI)](https://github.com/mukoubuchi/vector-search-hands-on/actions/workflows/ci.yml)\n[![E2E](https://img.shields.io/github/actions/workflow/status/mukoubuchi/vector-search-hands-on/e2e-smoke.yml?branch=main\u0026label=E2E)](https://github.com/mukoubuchi/vector-search-hands-on/actions/workflows/e2e-smoke.yml)\n[![Docs](https://img.shields.io/github/actions/workflow/status/mukoubuchi/vector-search-hands-on/deploy-docs.yml?branch=main\u0026label=docs)](https://mukoubuchi.github.io/vector-search-hands-on/)\n[![Release](https://img.shields.io/github/v/release/mukoubuchi/vector-search-hands-on)](https://github.com/mukoubuchi/vector-search-hands-on/releases/latest)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python\u0026logoColor=white)\n![Milvus](https://img.shields.io/badge/Milvus-2.6.18-00A1EA)\n\nNext-generation vector search in practice using **Building Blocks** and **IBM Bob**\n\n## Features of This Hands-on\n\n### Value of Building Blocks + IBM Bob\n\nThis hands-on demonstrates how combining **Building Blocks** (pre-built technical components) with **IBM Bob** (an AI development assistant) can complete development that would typically take days to weeks in **approximately 90 minutes**.\n\n| Development Method | Time Required | Required Skills | Code Quality |\n|---------|---------|------------|-----------|\n| **Traditional development** | Days to weeks | Programming, DB design, API design | Depends on developer skills |\n| **IBM Bob only** | Hours to days | Basic technical understanding | High quality but time-consuming |\n| **Building Blocks + IBM Bob** | Minutes to hours | Just natural language instructions | Production-level high quality |\n\n### Building Block Used\n\n**Vector Search Builder** (Milvus-based)\n\n- Milvus database setup and management\n- Local embedding model integration with Hugging Face Transformers\n- Sample product data ingestion workflow\n- Vector search optimization\n\n### Integration with IBM Bob\n\nUsing Vector Search Builder mode, IBM Bob provides:\n\n- AI assistant specialized for Vector Search\n- Code generation with understanding of Building Blocks features\n- Implementation support based on best practices\n- Feature addition and customization via natural language instructions\n\n## Architecture\n\n![Vector Search Hands-on architecture](docs/images/hands-on-architecture.svg)\n\n## Quick Start\n\n### For Instructors\n\n#### Port Configuration\n\nThis hands-on uses the following ports:\n\n| Service | Port | URL | Purpose |\n|---------|--------|-----|------|\n| **MkDocs (development)** | 8000 | \u003chttp://localhost:8000\u003e | Document editing (with auto-reload) |\n| **MkDocs (container)** | 8001 | \u003chttp://localhost:8001\u003e | Participant sharing (stable delivery) |\n| **FastAPI (Swagger UI)** | 8002 | \u003chttp://localhost:8002/docs\u003e | Vector Search API (for participants) |\n| **Milvus** | 19530 | localhost:19530 | Vector database |\n\n**Important**:\n\n- Port 8000 is dedicated to MkDocs development (for instructor document editing)\n- Port 8002 is the FastAPI app (participants access Swagger UI)\n- Direct participants to `http://localhost:8002/docs`\n\n#### Remote Delivery Setup\n\nThis hands-on assumes remote participants. Use GitHub Pages for the documentation. For Milvus, **prefer a private network (Tailscale, VPN) or an organization-approved cloud endpoint**; use an ngrok TCP tunnel only as a fallback — Milvus gRPC traffic is not TLS-encrypted, so credentials and data transit an ngrok tunnel in cleartext.\n\nMilvus credentials are generated automatically: `./start-all.sh` replaces the default `root/Milvus` password with a random one on first start, prints it, and stores it as `MILVUS_PASSWORD` in `setup/instructor/.env`. Share that password with participants.\n\n**1. Publish documentation with GitHub Pages**\n\n\u003e **Note**: Free accounts require the repository to be **Public**\n\n```bash\n# 1. Create a Public repository on GitHub.com and update remote\ngit remote set-url origin https://github.com/mukoubuchi/vector-search-hands-on.git\ngit push -u origin main\n\n# 2. Configure GitHub repository settings\n# Settings -\u003e Pages -\u003e Source: select \"GitHub Actions\"\n\n# 3. After auto-deploy completes, access at:\n# https://mukoubuchi.github.io/vector-search-hands-on/\n```\n\n**2-a. Expose Milvus over a private network (recommended)**\n\nUse Tailscale, an organization VPN, or a cloud VM so that traffic never crosses the public internet unencrypted:\n\n```bash\n# 1. Start Milvus environment (generates and prints the root password)\ncd setup/instructor\n./start-all.sh\n\n# 2. Share with participants\n# - Milvus host: the instructor's private-network address (e.g. Tailscale IP), port 19530\n# - Milvus password: the value printed by start-all.sh\n```\n\n**2-b. Fallback: publish Milvus with ngrok TCP**\n\n\u003e **Security note**: Milvus gRPC traffic is **not TLS-encrypted**, so the password and data transit the ngrok tunnel in cleartext on the public internet. Use this only for throwaway hands-on data, and stop the tunnel immediately after the session. Authentication itself is enforced (`COMMON_SECURITY_AUTHORIZATIONENABLED=true`) with the password generated by `start-all.sh`.\n\n\u003e **Note**: ngrok TCP endpoints may require account identity verification, such as adding a credit or debit card, even on a free account. If `ERR_NGROK_8013` appears, complete ngrok verification or use one of the alternatives above.\n\n\u003e **Network note**: Corporate VPN or DNS security products such as Cisco Umbrella may block ngrok TCP tunnels or prevent the ngrok hostname from resolving correctly. Disconnecting the VPN may not be enough if Cisco Umbrella or a similar product remains active. If participants cannot connect through ngrok, use an organization-approved same-network, private-network, or cloud VM alternative.\n\n```bash\n# 1. Start Milvus environment (generates and prints the root password)\ncd setup/instructor\n./start-all.sh\n\n# 2. Start a TCP tunnel in a separate terminal\nngrok tcp 19530\n```\n\nIf ngrok shows:\n\n```text\nForwarding  tcp://0.tcp.jp.ngrok.io:12345 -\u003e localhost:19530\n```\n\nshare these values with remote participants:\n\n```env\nMILVUS_HOST=0.tcp.jp.ngrok.io\nMILVUS_PORT=12345\nMILVUS_USER=root\nMILVUS_PASSWORD=\u003cthe password printed by start-all.sh\u003e\n```\n\nParticipants must update `MILVUS_HOST`, `MILVUS_PORT`, and `MILVUS_PASSWORD` in `setup/participant/.env`, and set `COLLECTION_NAME` to a name unique to each participant (e.g. `products_taro`) because the Milvus instance is shared. Do not include `tcp://` in `MILVUS_HOST`.\n\n**3. Stop the environment after hands-on**\n\n```bash\ncd setup/instructor\n./stop-all.sh\n# Stops Milvus, MkDocs, and any FastAPI demo running on port 8002\n```\n\n**Alternative: Local delivery (same network only)**\n\nUse this only when participants are on the same LAN, Wi-Fi, or VPN.\n\n```bash\n# 1. Start Milvus environment and MkDocs\ncd setup/instructor\n./start-all.sh\n\n# 2. Check IP address\nifconfig | grep \"inet \" | grep -v 127.0.0.1\n\n# 3. Share with participants\n# - Milvus: \u003cIP address\u003e:19530 (root / password printed by start-all.sh)\n# - Documentation: http://\u003cIP address\u003e:8001\n```\n\n**Other delivery methods:**\n\n- A public cloud VM that runs Milvus or forwards TCP `19530`\n- ngrok HTTP for temporary documentation access\n- Cloudflare Tunnel (free, fixed URL)\n\nDetails: [setup/instructor/deploy-docs-to-cloud.md](setup/instructor/deploy-docs-to-cloud.md)\n\n### For Participants\n\n**Distributed files** (instructors download them from the [latest release assets](https://github.com/mukoubuchi/vector-search-hands-on/releases/latest), or build them with `./setup/instructor/build-participant-zips.sh`):\n\n- `vector-search-builder-en.zip` — Minimal participant package with English rules and scripts\n- `vector-search-builder-ja.zip` — Minimal participant package with Japanese rules and scripts (日本語版)\n\nThe two packages use the same participant scripts. Each package includes only the sample data file for its language, and its packaged `.env.example` is generated from the matching source template (`.env.example.en` / `.env.example.ja`) so sample product data and runtime messages match the hands-on language.\n\nThe participant scripts read Milvus credentials from `setup/participant/.env`; credentials are not hardcoded in the Python code. Production-oriented review suggestions such as validation, logging, CORS restrictions, caching, and tests are treated as Part 3 code review discussion points.\n\nEach zip contains only:\n\n- `.bob/custom_modes.yaml`\n- `.bob/rules-vector-search-builder/` (3 XML rule files)\n- `setup/participant/` (`.env.example`, Python scripts, and `requirements.txt`)\n\nInstructor files, documentation files, local `.env` files, Python caches, and system files are intentionally excluded.\n\n**Setup steps**:\n\n1. Extract the zip file for your language\n\n   - English: `vector-search-builder-en.zip`\n   - Japanese: `vector-search-builder-ja.zip`\n   - Mac: Double-click\n   - Windows: Right-click → \"Extract All\"\n\n2. Open the extracted folder in IBM Bob IDE\n\n   - `File` → `Open Folder`\n\n3. Configure connection information received from instructor\n\n   - Copy `setup/participant/.env.example` to create `setup/participant/.env`\n   - For remote sessions, set both `MILVUS_HOST` and `MILVUS_PORT` to the values shared by the instructor\n   - For same-network sessions, set the IP address shared by the instructor in `MILVUS_HOST`\n   - Set `MILVUS_PASSWORD` to the password distributed by the instructor\n   - Set `COLLECTION_NAME` to a name unique to you (e.g. `products_taro`) — Milvus is shared by all participants\n\n4. Reload IBM Bob\n\n   - Mac: `Cmd+Shift+P` → \"Reload Window\"\n   - Windows: `Ctrl+Shift+P` → \"Reload Window\"\n\n5. Select Vector Search Builder mode\n\n   - \"Vector Search Builder\" appears in the \"Mode\" selector at the bottom right\n   - Select \"Vector Search Builder\" from the \"Mode\" selector\n\n6. Start hands-on\n\nDetails: [docs/preparation.md](docs/preparation.md)\n\n## Hands-on Flow\n\n| Part | Content | Time | Learning |\n|-------|------|---------|---------|\n| [Preparation](docs/preparation.md) | Building Block setup | 15 min | Vector Search Builder installation |\n| [Part 1](docs/part1.md) | Experience Vector Search | 20 min | How semantic search works and its value |\n| [Part 2](docs/part2.md) | Add features with IBM Bob | 30 min | Development experience via natural language |\n| [Part 3](docs/part3.md) | Verification and review | 15 min | Code quality verification |\n| [Summary](docs/summary.md) | Review and Q\u0026A | 10 min | Value recap and next steps |\n\n**Total**: approximately 90 minutes\n\n## What You'll Learn\n\n### Value of Building Blocks\n\n- **Ready to use**: Start immediately without complex configuration or learning\n- **Best practices**: Optimal implementation patterns designed by IBM's engineering team\n- **Domain-specific**: Provides Vector Search-specific guidance and implementation patterns\n- **Customizable**: Flexibly extend to meet business requirements using IBM Bob\n\n### Utilizing IBM Bob\n\n- **Natural language instructions**: Just tell it what you want to do\n- **Automatic code generation**: Automatically generates high-quality code\n- **Code review**: Points out code issues\n- **Integration with Building Blocks**: Provides technology-specific support through custom modes\n\n### Improved Development Efficiency\n\n**Traditional development**:\n\n- Read Milvus documentation (hours)\n- Learn Python SDK (hours)\n- Select and integrate embedding model (hours to days)\n- Implement code from scratch (days)\n\n**Building Blocks + IBM Bob**:\n\n- Install Vector Search Builder (minutes)\n- Give natural language instructions to IBM Bob (minutes)\n- Done (minutes to hours)\n\n## Documentation\n\n### For Instructors\n\n- **Document delivery methods**: [`setup/instructor/deploy-docs-to-cloud.md`](setup/instructor/deploy-docs-to-cloud.md)\n- **Instructor information sharing**: [`setup/instructor/instructor-share-info.md`](setup/instructor/instructor-share-info.md)\n- **Translation sync guide**: [docs/translation-sync.md](docs/translation-sync.md) (internal source guide; excluded from the published MkDocs navigation)\n\n### For Participants\n\n- **Preparation**: [docs/preparation.md](docs/preparation.md)\n- **Part 1 - Experience Vector Search**: [docs/part1.md](docs/part1.md)\n- **Part 2 - Add features with IBM Bob**: [docs/part2.md](docs/part2.md)\n- **Part 3 - Verification and review**: [docs/part3.md](docs/part3.md)\n- **Summary**: [docs/summary.md](docs/summary.md)\n- **Feedback**: [docs/feedback.md](docs/feedback.md)\n\n### Japanese Documentation\n\nAll documentation is available in Japanese under [`docs/ja/`](docs/ja/).\n\n### For Developers\n\n- **Translation sync**: English and Japanese participant-facing docs and paired SVG diagrams are sync-checked by GitHub Actions. Pull Requests fail when counterparts are missing; pushes to `main` create a tracking issue. See [Translation Sync Guide](docs/translation-sync.md) for details. This guide is kept in source control but excluded from the published MkDocs site.\n- **GitHub Actions**: Automated workflows for CI checks ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)), GitHub Pages deployment ([`.github/workflows/deploy-docs.yml`](.github/workflows/deploy-docs.yml)), translation sync ([`.github/workflows/sync-translations.yml`](.github/workflows/sync-translations.yml), [`.github/workflows/sync-translations-ja-to-en.yml`](.github/workflows/sync-translations-ja-to-en.yml)), the E2E smoke test ([`.github/workflows/e2e-smoke.yml`](.github/workflows/e2e-smoke.yml)), and release packaging ([`.github/workflows/release.yml`](.github/workflows/release.yml)).\n- **Releasing**: run the E2E smoke test on `main` first, then create a GitHub release with a `vX.Y.Z` tag (e.g. `gh release create v1.3.0 --title v1.3.0 --notes \"...\"`). The release workflow builds the participant zips from the tagged sources and attaches them to the release automatically.\n\n## Required Tools\n\n**Instructors**: a container runtime — Colima or Podman recommended (Docker Desktop also works where your organization licenses it) — and Python 3 with `pymilvus` (used by `start-all.sh` to rotate the Milvus root password)\n\n**Participants**: IBM Bob 1.0.3 (IDE with Building Blocks support)\n\n## Unique Innovations in This Hands-on\n\n### 1. Instructor-Participant Separation Architecture\n\n**Building Blocks alone**:\n\n- Each person builds their own Milvus environment (Docker/Podman/Colima)\n- Individually downloads embedding models (approximately 460 MB)\n- Environment setup takes about 30 minutes\n\n**This hands-on's innovation**:\n\n- **Instructor**: Centrally manages Milvus environment (`setup/instructor/docker-compose.yml`)\n- **Participants**: Participate with IBM Bob, the Vector Search Builder mode, participant scripts, and connection information only\n- **Result**: Setup time reduced from 30 minutes to 5 minutes\n\n### 2. Hybrid Delivery Support\n\n**Building Blocks alone**:\n\n- Assumes local environment execution\n\n**This hands-on's innovation**:\n\n- **On-site**: Local network sharing (`http://instructor IP:8001`)\n- **Remote**: Document deployment to GitHub Pages\n- **Result**: Supports on-site/remote/hybrid delivery\n\n### 3. API Key-Free Design\n\n**Building Blocks alone**:\n\n- Cloud-based embedding options often require API keys\n- Participants configure credentials individually\n\n**This hands-on's innovation**:\n\n- **Hugging Face Transformers** used (no API key required)\n- **Local execution**: Works with internet connection only\n- **Result**: Reduces participant preparation burden\n\n### 4. Progressive Learning Path\n\n**Building Blocks alone**:\n\n- Focuses on technical implementation\n\n**This hands-on's innovation**:\n\n- **Part 1**: Experience Vector Search (understanding)\n- **Part 2**: Add features with IBM Bob (practice)\n- **Part 3**: Code review and improvement (application)\n- **Result**: Even beginners can progress from understanding → practice → application\n\n## Other Building Blocks Features\n\nIn addition to Vector Search Builder, there are many Building Blocks with dedicated Bob Modes:\n\n- **Agent Builder**: Build autonomous AI agents and voice-enabled agents\n- **Multi-Agent Orchestration**: Coordinated control of multiple agents\n- **Agent Ops**: AI agent operations management and performance monitoring\n- **Model Evaluation**: Evaluation of Gen AI/predictive ML models\n- **Text2SQL**: Generate SQL queries from natural language\n- **Data Pipeline AI-Generated**: Automated data pipeline generation\n- **Zero-Copy Lakehouse**: Lakehouse construction without data copying\n- **IaaS**: Terraform/CloudFormation template generation\n- **Automated Resilience and Compliance**: Automated resilience and compliance\n- **Automated Resource Management**: Automated resource management and cost optimization\n- **Secrets Management**: Management of secrets and non-human identities\n\nDetails: [Building Blocks Documentation](https://ibm-self-serve-assets.github.io/building-blocks-docs/)\n\n## Tech Stack\n\n- **Building Block**: Vector Search Builder (Milvus-based)\n- **AI Development Assistant**: IBM Bob\n- **Vector Database**: Milvus 2.6.18 (pymilvus 2.6.15)\n- **Embedding Model**: Hugging Face Transformers (`paraphrase-multilingual-MiniLM-L12-v2`, sentence-transformers 5.5)\n- **Web Framework**: FastAPI 0.136 / Uvicorn\n- **Programming Language**: Python 3.11\n- **Documentation**: MkDocs Material (with i18n plugin — English / 日本語)\n- **CI/CD**: GitHub Actions (auto-deploy to GitHub Pages, translation sync check, lint, zip packaging, E2E smoke test)\n\n## Directory Structure\n\n```\nvector-search-hands-on/\n├── .github/                               # GitHub Actions and Dependabot configuration\n│   ├── dependabot.yml                     # Automated dependency updates\n│   └── workflows/\n│       ├── ci.yml                         # CI checks (lint, build, zip verification)\n│       ├── deploy-docs.yml                # GitHub Pages auto-deploy\n│       ├── e2e-smoke.yml                  # Full-stack smoke test (manual trigger)\n│       ├── release.yml                    # Attach participant zips to releases\n│       ├── sync-translations.yml          # Translation sync check (EN → JA, PR + main)\n│       └── sync-translations-ja-to-en.yml # Translation sync check (JA → EN, PR + main)\n├── docs/                                  # Hands-on documentation (MkDocs)\n│   ├── index.md                           # Home\n│   ├── preparation.md                     # Preparation\n│   ├── part1.md                           # Part 1: Experience Vector Search\n│   ├── part2.md                           # Part 2: Add features with IBM Bob\n│   ├── part3.md                           # Part 3: Verification and Review\n│   ├── summary.md                         # Summary\n│   ├── feedback.md                        # Participant feedback form\n│   ├── translation-sync.md                # Internal translation sync guide (excluded from MkDocs nav)\n│   ├── readme.md                          # docs/ directory structure guide\n│   ├── ja/                                # Japanese translations\n│   │   ├── readme.md                      # Japanese docs directory structure guide\n│   │   ├── index.md                       # Home\n│   │   ├── preparation.md                 # Preparation\n│   │   ├── part1.md                       # Part 1: Experience Vector Search\n│   │   ├── part2.md                       # Part 2: Add features with IBM Bob\n│   │   ├── part3.md                       # Part 3: Verification and Review\n│   │   ├── summary.md                     # Summary\n│   │   ├── feedback.md                    # Participant feedback form\n│   │   └── translation-sync.md            # Internal translation sync guide (excluded from MkDocs nav)\n│   ├── images/                            # Diagrams and SVG images (EN/JA where needed)\n│   ├── javascripts/                       # Custom JavaScript\n│   └── stylesheets/                       # Custom CSS\n├── setup/\n│   ├── instructor/                        # Instructor setup\n│   │   ├── docker-compose.yml             # Milvus environment definition\n│   │   ├── mkdocs.Dockerfile              # Docs container image (pinned plugins)\n│   │   ├── .env.example                   # Environment variables template\n│   │   ├── start-all.sh                   # Start services, generate credentials\n│   │   ├── stop-all.sh                    # Stop services and FastAPI demo on port 8002\n│   │   ├── build-participant-zips.sh      # Regenerate participant distribution zips\n│   │   ├── deploy-docs-to-cloud.md        # Document delivery methods\n│   │   └── instructor-share-info.md       # Instructor information sharing\n│   └── participant/                       # Participant setup\n│       ├── .bob/                          # Building Block (Vector Search Builder mode)\n│       │   ├── custom_modes.yaml          # IBM Bob custom mode definition\n│       │   └── rules-vector-search-builder/ # Vector Search Builder specific rules\n│       │       ├── 1_vector_search_workflow.xml\n│       │       ├── 2_best_practices.xml\n│       │       └── 3_common_patterns.xml\n│       ├── .env.example.en                # English connection information template\n│       ├── .env.example.ja                # Japanese connection information template\n│       ├── requirements.txt               # Python dependencies\n│       ├── common.py                      # Shared environment, language, connection, and model helpers\n│       ├── schema.py                      # Shared Milvus schema, index, and search settings\n│       ├── app.py                         # FastAPI vector search application\n│       ├── insert_sample_data.py          # Sample data insertion script\n│       ├── sample_products.py             # Language-aware sample data selector\n│       ├── sample_products_en.py          # English sample product data\n│       ├── sample_products_ja.py          # Japanese sample product data\n│       ├── test_connection.py             # Connection test\n│       └── test_embeddings_hf.py          # Embedding model test\n├── lib/                                   # Common libraries\n│   ├── common.sh                          # Common shell functions\n│   └── check_translation_sync.sh          # Shared translation sync checker\n├── LICENSE                                # Apache-2.0 license\n├── mkdocs.yml                             # MkDocs configuration\n└── README.md                              # This file\n```\n\nThe participant distribution zips (`vector-search-builder-en.zip` / `vector-search-builder-ja.zip`) are **not committed**: they are built from the sources by the release workflow and attached to every GitHub release.\n\n### Distribution Zip Contents\n\nThe participant zip files are intentionally minimal and contain only the files needed by participants.\n\nHow the packages are distributed:\n\n- **Releases (canonical)**: on every `v*` tag push, the release workflow builds the zips from the repository sources and attaches them to the GitHub release — download them from the [release page](https://github.com/mukoubuchi/vector-search-hands-on/releases)\n- **Local build**: to package the current working tree (e.g. between releases), run `./setup/instructor/build-participant-zips.sh`; the zips are written to the repository root and are gitignored\n\nCI builds the zips on every push to ensure the packaging script keeps working.\n\n- `vector-search-builder-en.zip`\n- `vector-search-builder-ja.zip`\n\nCommon files:\n\n```\n.bob/custom_modes.yaml\n.bob/rules-vector-search-builder/1_vector_search_workflow.xml\n.bob/rules-vector-search-builder/2_best_practices.xml\n.bob/rules-vector-search-builder/3_common_patterns.xml\nsetup/participant/.env.example\nsetup/participant/app.py\nsetup/participant/common.py\nsetup/participant/insert_sample_data.py\nsetup/participant/requirements.txt\nsetup/participant/sample_products.py\nsetup/participant/schema.py\nsetup/participant/test_connection.py\nsetup/participant/test_embeddings_hf.py\n```\n\nLanguage-specific sample data:\n\n- `vector-search-builder-en.zip`: `setup/participant/sample_products_en.py`\n- `vector-search-builder-ja.zip`: `setup/participant/sample_products_ja.py`\n\nLanguage-specific `.env.example` source template:\n\n- `vector-search-builder-en.zip`: generated from `setup/participant/.env.example.en`\n- `vector-search-builder-ja.zip`: generated from `setup/participant/.env.example.ja`\n\nMilvus credentials in the packaged `.env.example` are copied into `.env` by participants and read from environment variables at runtime. `test_connection.py`, `insert_sample_data.py`, and `app.py` all use the shared helpers in `common.py`, so user/password connection settings behave consistently.\n\nDo not include `docs/`, `setup/instructor/`, local `.env` files, `__pycache__/`, `.DS_Store`, or other generated/local files in participant zip packages.\n\n### Key Directory Descriptions\n\n#### `setup/participant/.bob/` - Building Block\n\n**Vector Search Builder mode definition** (provided by IBM). Packaged into the participant zips at their root as `.bob/`.\n\n- `custom_modes.yaml` — IBM Bob custom mode registration\n- `rules-vector-search-builder/` — Vector Search-specialized rules (workflow, best practices, common patterns)\n- IBM Bob provides Vector Search-specialized support\n- Understands how to operate Milvus database\n- Applies vector search best practices\n- Knows how to integrate embedding models\n\n#### `docs/` - Hands-on Documentation\n\n**Learning content built with MkDocs Material**\n\n- Progressive learning path (understanding → practice → application)\n- Interactive code examples\n- Visual diagrams and animations\n\n#### `setup/instructor/` - Instructor Environment\n\n**Centralized Milvus environment management**\n\n- Environment setup with Docker Compose\n- One-command start/stop for Milvus, MkDocs, and the FastAPI demo port\n- Network sharing and remote delivery support\n\n#### `setup/participant/` - Participant Tools\n\n**FastAPI application and connection tests**\n\n- `app.py` — FastAPI vector search application (Swagger UI at port 8002)\n- `insert_sample_data.py` — Sample product data insertion script\n- `common.py` — Shared language selection, `.env` loading, Milvus authentication, and embedding model loading\n- `schema.py` — Shared collection schema, index parameters, search parameters, and product text mapping\n- `sample_products.py` and the package-specific `sample_products_en.py` or `sample_products_ja.py` — Language-specific sample product data selected by `PARTICIPANT_LANGUAGE`\n- Milvus connection test\n- Embedding model verification\n- Environment variable configuration template\n\n## Support\n\nIf you have questions or encounter issues, please ask the instructor.\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmukoubuchi%2Fvector-search-hands-on","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmukoubuchi%2Fvector-search-hands-on","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmukoubuchi%2Fvector-search-hands-on/lists"}