{"id":18730039,"url":"https://github.com/primeqa/create-primeqa-app","last_synced_at":"2025-04-12T17:07:15.299Z","repository":{"id":90994594,"uuid":"557432185","full_name":"primeqa/create-primeqa-app","owner":"primeqa","description":"Create your own search app quickly with only a couple of commands","archived":false,"fork":false,"pushed_at":"2024-03-19T18:31:38.000Z","size":51,"stargazers_count":8,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T11:21:46.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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/primeqa.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}},"created_at":"2022-10-25T17:19:30.000Z","updated_at":"2023-04-29T01:00:29.000Z","dependencies_parsed_at":"2024-03-19T19:54:44.437Z","dependency_job_id":null,"html_url":"https://github.com/primeqa/create-primeqa-app","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primeqa%2Fcreate-primeqa-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primeqa%2Fcreate-primeqa-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primeqa%2Fcreate-primeqa-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primeqa%2Fcreate-primeqa-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/primeqa","download_url":"https://codeload.github.com/primeqa/create-primeqa-app/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248602312,"owners_count":21131616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-07T14:33:55.663Z","updated_at":"2025-04-12T17:07:15.261Z","avatar_url":"https://github.com/primeqa.png","language":"Shell","readme":"\u003c!---\nCopyright 2022 PrimeQA Team\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n--\u003e\n\u003c!-- START sphinx doc instructions - DO NOT MODIFY next code, please --\u003e\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"static/PrimeQA.png\" width=\"150\"/\u003e\n\u003c/div\u003e\n\u003c!-- END sphinx doc instructions - DO NOT MODIFY above code, please --\u003e\n\n# PrimeQA Application\n\nThis repository provides easy scripts to run PrimeQA applications via docker.\n\u003cbr\u003e\n\n[![LICENSE|Apache2.0](https://img.shields.io/github/license/saltstack/salt?color=blue)](https://www.apache.org/licenses/LICENSE-2.0.txt)\n\n\u003ch3\u003e ✅ Prerequisites \u003c/h3\u003e\n\nWe use [docker](https://www.docker.com/) and [docker-compose](https://docs.docker.com/compose/) to run our application. Make sure you have the most up-to-date version of those tools.\n\n⚠️ **Important**: Make sure your docker has read/write permissions in the existing directory and sub-directories.\n\n\u003ch3\u003e 💻 Hardware Requirements \u003c/h3\u003e\n\nOS: Ubuntu 20.04.4 LTS\n\nMemory: 32GB (64GB - Recommended)\n\nGPU: NVIDIA Corporation GV100GL [V100 PCIe 16GB]\n\nNVIDIA Driver version: 470.141.03\n\nDisk space: 50 GB is required for the docker, 25 GB of available free space is needed in the docker container storage\n\n\n\u003ch3\u003e 🧩 Release Notes \u003c/h3\u003e\n\n\u003ch4\u003e 🧩 PrimeQA services v0.14.3 with PrimeQA UI and Orchestrator v0.0.4 \u003c/h4\u003e\n\nPrimeQA services now adds support for:\n\n**Rerankers** \n\nFor more details:\n\n- [Reranker Component](https://github.com/primeqa/primeqa/tree/main/primeqa/components#reranker-components)\n- [ColBERT Reranker model](https://github.com/primeqa/primeqa/tree/main/primeqa/services#drop-in-a-reranker-model)\n\n**Generative Readers**\n\nFor more details on `GenerativeReader` and `PromptReader`:\n\n- [Generative Reader Components](https://github.com/primeqa/primeqa/tree/main/primeqa/components#generative-reader)\n\n\u003ch4\u003e 🧩 PrimeQA services v0.11.8 \u003c/h4\u003e\n\nPrimeQA services now adds support for `BM25` and `DPR` Retrievers.\n\nThe `information.json` file in the index directory must include an `engine_type` files set to one of `BM25`, `ColBERT` or `DPR`.\n\nIf you have existing ColBERT indexes in `primeqa-store/indexes`, please update the `information.json` file in the index directory to include a configuration section as follows:\n\n```\n  \"configuration\": {\n    \"engine_type\": ColBERT,\n    \"checkpoint\": \u003ccheckpoint-dir-name\u003e\n  }\n```\n\n\u003ch3\u003e 🧩 Installation \u003c/h3\u003e\n\n1.  Set the environment variable `PUBLIC_IP` to the ip address of the localhost. This host must be reachable from where you will be accessing via the browser. Otherwise, please use VNC to access the host.\n    If accessing the application via the browser locally, `PUBLIC_IP` can be set to `localhost`.\n\n        ```\n        export PUBLIC_IP=\u003chostname\u003e\n        ```\n\n2.  Please ensure that the following three ports are free and available: `50051`, `50059` and `82`\n\n3.  Launch the container using `bash` in `cpu` (default) or `gpu` mode:\n\n    CPU mode (default):\n\n    ```\n    launch.sh\n    ```\n\n    GPU mode:\n\n    ```\n    launch.sh -m gpu\n    ```\n\n🚨 **Note**: This process will take a while to complete as it will download necessary docker images and bring up services.\n\n\u003ch3\u003e⚙️ Configuration \u003c/h3\u003e\n\n1. Run `docker ps` to verify that all the three containers (primeqa-ui, primqa-orchestrator and primeqa-service) are running.\n\n2. You will need to configure a few additional settings before first use. These setting are intentionally left blank for security purposes.\n\n3. Settings are defined in the file `orchestrator-store/primeqa.json`. Create this file and copy-pase the Reader and Retriever setting that you would like to use from the examples below\n\n   a. To use the IBM® Watson Discovery retriever and PrimeQA reader, first configure a IBM® Watson Discovery Cloud instance using the instructions [here](https://cloud.ibm.com/catalog/services/watson-discovery) and create a collection index.\n\n   ```json\n   {\n     \"retrievers\": {\n       \"Watson Discovery\": {\n         \"service_endpoint\": \"\u003cIBM® Watson Discovery Cloud/CP4D Instance Endpoint\u003e\",\n         \"service_api_key\": \"\u003cAPI key (ONLY If using IBM® Watson Discovery Cloud instance)\u003e\",\n         \"service_project_id\": \"\u003cIBM® Watson Discovery Project ID\u003e\"\n       }\n     },\n     \"readers\": {\n       \"PrimeQA\": {\n         \"service_endpoint\": \"primeqa:50051\",\n         \"beta\": 0.7\n       }\n     }\n   }\n   ```\n\n   b. To use the PrimeQA retriever and PrimeQA reader, first setup the collection index for the Retriever using the instructions [here](https://github.com/primeqa/primeqa/tree/main/primeqa/services#-store).\n\n   ```json\n   {\n     \"retrievers\": {\n       \"PrimeQA\": {\n         \"service_endpoint\": \"primeqa:50051\"\n       }\n     },\n     \"readers\": {\n       \"PrimeQA\": {\n         \"service_endpoint\": \"primeqa:50051\",\n         \"beta\": 0.7\n       }\n     }\n   }\n   ```\n\n   NOTE: The final scoring and ranking is done with a weighted sum of the Reader answer scores and Retriever search hits scores. The `beta` field is the weight assigned to the reader scores and `1-beta` is the weight assigned to the retriever scores.\n\n4. Please allow 30 seconds for the primeqa-orchestrator to establish connectivity to IBM® Watson Discovery and PrimeQA service.\n\n\u003ch3\u003e 🧪 Testing \u003c/h3\u003e\n\n1. You can test the PrimeQA orchestrator's connectivity to your IBM® Watson Discovery (WD) instance by executing the [GET] `/retrievers/{retriever_id}/collections` endpoint.\n\n   ```sh\n   curl -X 'GET' \"http://{$PUBLIC_IP}:50059/retrievers/WatsonDiscovery/collections\" -H 'accept: application/json'\n   ```\n\n2. To see all available retrievers, execute [GET] `/retrievers` endpoint\n\n   ```sh\n   curl -X 'GET' \"http://{$PUBLIC_IP}:50059/retrievers\" -H 'accept: application/json'\n   ```\n\n3. To run a sample question answering query, execute [POST] `/ask` endpoint\n\n   a. Using the IBM® Watson Discovery Retriever (You must provide the name of your \u003ccollection_id\u003e)\n\n   ```sh\n   curl -X 'POST' \"http://{$PUBLIC_IP}:50059/ask\" -H 'accept: application/json' \\\n   -H 'Content-Type: application/json' \\\n   -d '{\n   \"question\": \"\u003cSAMPLE QUERY\u003e\",\n   \"retriever\": {\n       \"retriever_id\": \"WatsonDiscovery\"\n   },\n   \"collection\": {\n       \"collection_id\": \"\u003ccollection_id\u003e from collections returned by [GET]/collections API.\",\n       \"name\": \"Name of corresponding collection\"\n   },\n   \"reader\": {\n       \"reader_id\": \"ExtractiveReader\"\n   }\n   }'\n   ```\n\n   b. Using the PrimeQA Retriever (You must provide the name of your \u003ccollection_id\u003e)\n\n   ```sh\n   curl -X 'POST' \"http://{$PUBLIC_IP}:50059/ask\" -H 'accept: application/json' \\\n   -H 'Content-Type: application/json' \\\n   -d '{\n   \"question\": \"\u003cSAMPLE QUERY\u003e\",\n   \"retriever\": {\n       \"retriever_id\": \"ColBERTRetriever\"\n   },\n   \"collection\": {\n       \"collection_id\": \"\u003ccollection_id\u003e from collections returned by [GET]/collections API.\",\n       \"name\": \"Name of corresponding collection\"\n   },\n   \"reader\": {\n       \"reader_id\": \"ExtractiveReader\"\n   }\n   }'\n   ```\n\n4. To run reading:\n\n   ```sh\n   curl -X 'POST' \\\n   \"http://{$PUBLIC_IP}:50059/GetAnswersRequest\" \\\n   -H 'accept: application/json' \\\n   -H 'Content-Type: application/json' \\\n   -d '{\n   \"question\": \"Where was Genghis Khan buried?\",\n   \"contexts\": [\n       \"Before Genghis Khan died, he assigned Ögedei Khan as his successor and split his empire into khanates among his sons and grandsons. He died in 1227 after defeating the Western Xia. He was buried in an unmarked grave somewhere in Mongolia at an unknown location.  His descendants extended the Mongol Empire across most of Eurasia by conquering or creating vassal states out of all of modern-day China, Korea, the Caucasus, Central Asia, and substantial portions of modern Eastern Europe, Russia, and Southwest Asia. Many of these invasions repeated the earlier large-scale slaughters of local populations. As a result, Genghis Khan and his empire have a fearsome reputation in local histories..\"\n   ],\n   \"reader\": {\n       \"reader_id\": \"ExtractiveReader\",\n       \"parameters\": [\n       {\n           \"parameter_id\": \"max_num_answers\",\n           \"value\": 5\n       }\n       ]\n   }\n   }'\n   ```\n\n   Example Answer:\n\n   ```sh\n   [\n       {\n           \"text\": \"Mongolia at an unknown location\",\n           \"confidence_score\": 1,\n           \"start_char_offset\": 229,\n           \"end_char_offset\": 260,\n           \"context_index\": 0\n       }\n   ]\n   ```\n\n\u003ch2\u003e 🥁 Usage \u003c/h2\u003e\n\nYou can now open a browser of your choice (Mozilla Firefox/Google Chrome) and visit \"http://{PUBLIC_IP}:82\" to interact with the PrimeQA application. You will see our Retrieval, Reader and QuestionAnswering components. Some features include the ability to adjust settings and for users to provide feedback on retrieved answers.\n\n\u003ch2\u003e 💻 User Feedback \u003c/h2\u003e\n\nUsers can provide feedback via the 👍 and 👎 icons to the answers shown in the results page.\n\nTo use the feedback to fine-tune your Reader model\n\n1. Get the feedback data:\n\n```sh\n  curl -X 'GET' \\\n'http://localhost:50059/feedbacks?application=reading\u0026application=qa\u0026_format=primeqa' \\\n-H 'accept: application/json' \u003e feedbacks.json\n```\n\n2. Follow the instructions on how to finetune a PrimeQA reader with custom data [here](https://github.com/primeqa/primeqa/tree/main/examples/custom_mrc#finetuning-using-feedback-data). Generally, the finetuning would start with the model used when collecting the feedback data as specified in the `Model` field under `Reader` settings in the `Reading` and/or `QuestionAnswering` UI.\n\n3. To deploy the finetuned model, follow the instructions [here](#custom-mrc).\n\n\u003ch2 id=\"troubleshooting\"\u003e 🤨 Troubleshooting\u003c/h2\u003e\n\na. If the UI is not loading properly or a field is blank, please try these quick steps:\n\n- clear the browser cache and retry\n- restart the containers by running `terminate.sh` and then `launch.sh`\n\nb. To view the logs, use the docker logs command, for example:\n\n    ```\n    docker logs primeqa-ui\n    docker logs primeqa-orchestrator\n    docker logs primeqa-services\n    ```\n\n\u003ch2\u003e 🤨 Frequently Asked Questions (FAQs) \u003c/h2\u003e\n\n1. How do I switch to a different PrimeQA Reader model from the Huggingface model hub ?\n\n   Paste the model name from the [Huggingface model hub](https://huggingface.co/PrimeQA) into the `Model` field under `Reader` settings in the `Reading` and/or `QuestionAnswering` UI.\n\n   IMPORTANT: Only models trained using PrimeQA are supported. Other models based on Huggingface QA model will not work.\n\n2. \u003ca id=\"custom-reader\"\u003e\u003c/a\u003eHow do I use my custom model for reader in `Reading` or `QA` application?\n\n   By default the reader initializes the `PrimeQA/nq_tydi_sq1-reader-xlmr_large-20221110` from the Huggingface model hub.\n\n   To use your own reader model, place your model in a directory under `primeqa-store/models` directory. To point to your model from the UI, navigate to `Application Settings`, scroll down to `Reader Settings` and to `Model` and set it to `/store/model/\u003cmodel-dir\u003e`, replace `model-dir` with the name of the directory containing the model files.\n\n   The service will load the model and initialize a new reader. This may take a few minutes. Subsequent queries will use this model.\n\n3. How do I use my ColBERT index and checkpoint ?\n\n   Please follow the instructions [here](https://github.com/primeqa/primeqa/tree/main/primeqa/services#-store)\n\n4. The Corpus field is blank in the 'Retriever' or 'Question Answering' page\n\n   See [Troubleshooting](#troubleshooting)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimeqa%2Fcreate-primeqa-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprimeqa%2Fcreate-primeqa-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimeqa%2Fcreate-primeqa-app/lists"}